feat(portal-shell): add CI structural checks for routes, pages, codegen (P1-8)
ARCHITECTURE.md §10 P1-8: three structural checks wired into CI to prevent regressions identified in the §1.3 audit. Scripts (apps/portal-shell/scripts/): - check-route-table.ts: scans src/app/shell/**/page.tsx, parses route-permissions.ts (EXACT/PREFIX/DASHBOARD/PUBLIC_ROUTES), fails if any actual /shell/* route is unregistered. Reports ghost entries (EXACT declarations without page.tsx) as informational. - check-page-count.ts: asserts total page.tsx >= 13 and per-category minimums (dashboards/login/root/forbidden/catch-all/dev-templates). - check-codegen.ts: runs pnpm run codegen, fails if any output with skipDocumentsValidation:false has operations referencing non-existent schema fields (currently enforces dashboard-types.ts output from P1-7). npm scripts: check:routes / check:pages / check:codegen / check:all CI: .github/workflows/ci.yml quality-ts job — new "Portal-shell structural checks (P1-8)" step between typecheck and test. Acceptance (ARCHITECTURE.md §10 P1-8 — "CI 对预埋违规报红"): - Route violation: planted /shell/test-violation/page.tsx → check:routes exits 1 with "unregistered route" error; reverted → PASS - Codegen violation: planted non_existent_field in GetTeacherDashboard → check:codegen exits 1 with "Cannot query field" error; reverted → PASS - Page count: baseline=13, deleting any page.tsx triggers FAIL - Clean state: all 3 checks PASS (10 routes, 28 EXACT, 24 ghost entries informational, 13 pages, codegen 3 outputs SUCCESS) Refs: ARCHITECTURE.md §5.3, §10 P1-8, §11.6, §11.7 红线 #5
This commit is contained in:
SpecialX
64
apps/portal-shell/scripts/check-codegen.ts
Normal file
64
apps/portal-shell/scripts/check-codegen.ts
Normal file
@@ -0,0 +1,64 @@
|
||||
// Codegen contract validation check (ARCHITECTURE.md §10 P1-8 / §5.3)
|
||||
//
|
||||
// Runs graphql-codegen and fails if any output with skipDocumentsValidation:false
|
||||
// contains operations that reference non-existent schema fields.
|
||||
// This is the "codegen diff check" — it diffs operations against schema.
|
||||
//
|
||||
// Currently enforces:
|
||||
// - dashboard-types.ts output (skipDocumentsValidation: false, P1-7)
|
||||
// As more domains fix their operations, their outputs will be validated too.
|
||||
//
|
||||
// Usage: tsx scripts/check-codegen.ts
|
||||
// Exit: 0 = codegen success, 1 = validation errors
|
||||
//
|
||||
// Related: ARCHITECTURE.md §5.3 契约纪律, §10 P1-8
|
||||
import { execSync } from "node:child_process";
|
||||
|
||||
function main(): void {
|
||||
console.log("=== Codegen Contract Validation Check ===");
|
||||
console.log("Running: pnpm run codegen (normalize-schema + graphql-codegen)");
|
||||
console.log("");
|
||||
|
||||
try {
|
||||
const output = execSync("pnpm run codegen", {
|
||||
cwd: process.cwd(),
|
||||
encoding: "utf8",
|
||||
stdio: ["pipe", "pipe", "pipe"],
|
||||
});
|
||||
console.log(output);
|
||||
|
||||
// Check for validation failures even on exit 0 (some may be warnings)
|
||||
if (output.includes("GraphQL Document Validation failed")) {
|
||||
console.log("❌ Codegen reported validation failures despite exit 0");
|
||||
console.log("Result: FAIL");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(
|
||||
"Result: PASS (codegen succeeded, all validated outputs clean)",
|
||||
);
|
||||
process.exit(0);
|
||||
} catch (err: unknown) {
|
||||
const e = err as { stdout?: string; stderr?: string; message: string };
|
||||
const output = `${e.stdout ?? ""}\n${e.stderr ?? ""}`;
|
||||
console.log(output);
|
||||
|
||||
if (output.includes("GraphQL Document Validation failed")) {
|
||||
console.log(
|
||||
"❌ Codegen validation failed — operations reference non-existent schema fields",
|
||||
);
|
||||
console.log(
|
||||
" Fix: update operations/*.graphql.ts to match combined-schema.graphql",
|
||||
);
|
||||
console.log(
|
||||
" Or: keep skipDocumentsValidation: true for that output until schema is ready",
|
||||
);
|
||||
} else {
|
||||
console.log(`❌ Codegen failed: ${e.message}`);
|
||||
}
|
||||
console.log("Result: FAIL");
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
160
apps/portal-shell/scripts/check-page-count.ts
Normal file
160
apps/portal-shell/scripts/check-page-count.ts
Normal file
@@ -0,0 +1,160 @@
|
||||
// Page count baseline check (ARCHITECTURE.md §10 P1-8 / §11.6)
|
||||
//
|
||||
// Asserts that the total page.tsx count never drops below the baseline.
|
||||
// Prevents accidental route deletion. When adding new pages, update the
|
||||
// baseline in BASELINE.total. Per-category minimums catch regressions
|
||||
// in specific areas (dashboards, login, etc.).
|
||||
//
|
||||
// Usage: tsx scripts/check-page-count.ts
|
||||
// Exit: 0 = pass, 1 = below baseline
|
||||
//
|
||||
// Related: ARCHITECTURE.md §10 P1-8, §11.6 验收纪律
|
||||
import * as fs from "node:fs";
|
||||
import * as path from "node:path";
|
||||
|
||||
const APP_DIR = path.resolve(process.cwd(), "src/app");
|
||||
|
||||
interface Baseline {
|
||||
total: number;
|
||||
categories: Record<string, { pattern: string; min: number; label: string }>;
|
||||
}
|
||||
|
||||
// Baseline as of P1-8 (2026-07-22). Update when adding pages.
|
||||
const BASELINE: Baseline = {
|
||||
total: 13,
|
||||
categories: {
|
||||
dashboards: {
|
||||
pattern: "shell/{admin,teacher,student,parent}/page.tsx",
|
||||
min: 4,
|
||||
label: "Role dashboards (admin/teacher/student/parent)",
|
||||
},
|
||||
login: {
|
||||
pattern: "login/page.tsx",
|
||||
min: 1,
|
||||
label: "Login page",
|
||||
},
|
||||
root: {
|
||||
pattern: "page.tsx",
|
||||
min: 1,
|
||||
label: "Root redirect page",
|
||||
},
|
||||
forbidden: {
|
||||
pattern: "shell/forbidden/page.tsx",
|
||||
min: 1,
|
||||
label: "Forbidden page",
|
||||
},
|
||||
catchAll: {
|
||||
pattern: "shell/[[...route]]/page.tsx",
|
||||
min: 1,
|
||||
label: "Shell catch-all",
|
||||
},
|
||||
devTemplates: {
|
||||
pattern: "shell/dev/templates/**/page.tsx",
|
||||
min: 5,
|
||||
label: "Dev template pages",
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
function scanPages(): string[] {
|
||||
const pages: string[] = [];
|
||||
|
||||
function walk(dir: string, base: string): void {
|
||||
const entries = fs.readdirSync(dir, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
const rel = path.relative(base, full).replace(/\\/g, "/");
|
||||
if (entry.isDirectory()) {
|
||||
walk(full, base);
|
||||
} else if (entry.name === "page.tsx") {
|
||||
pages.push(rel);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
walk(APP_DIR, APP_DIR);
|
||||
return pages.sort();
|
||||
}
|
||||
|
||||
function matchGlob(pattern: string, relPath: string): boolean {
|
||||
// Glob → regex: ** (any path), * (within segment), {a,b} (alternation)
|
||||
let result = "";
|
||||
let i = 0;
|
||||
while (i < pattern.length) {
|
||||
const c = pattern[i];
|
||||
if (c === "*" && pattern[i + 1] === "*") {
|
||||
// ** — match anything including /; skip trailing /
|
||||
result += ".*";
|
||||
i += 2;
|
||||
if (pattern[i] === "/") i++;
|
||||
} else if (c === "*") {
|
||||
result += "[^/]*";
|
||||
i++;
|
||||
} else if (c === "{") {
|
||||
const end = pattern.indexOf("}", i);
|
||||
if (end === -1) {
|
||||
result += "\\{";
|
||||
i++;
|
||||
} else {
|
||||
const opts = pattern
|
||||
.slice(i + 1, end)
|
||||
.split(",")
|
||||
.map((s) => s.trim());
|
||||
result += `(${opts.join("|")})`;
|
||||
i = end + 1;
|
||||
}
|
||||
} else if (".+?^$()[]|\\".includes(c)) {
|
||||
result += `\\${c}`;
|
||||
i++;
|
||||
} else {
|
||||
result += c;
|
||||
i++;
|
||||
}
|
||||
}
|
||||
return new RegExp(`^${result}$`).test(relPath);
|
||||
}
|
||||
|
||||
function main(): void {
|
||||
const pages = scanPages();
|
||||
const total = pages.length;
|
||||
|
||||
console.log("=== Page Count Baseline Check ===");
|
||||
console.log(`Total page.tsx files: ${total} (baseline: ${BASELINE.total})`);
|
||||
console.log("");
|
||||
|
||||
// Per-category check
|
||||
let categoryFail = false;
|
||||
for (const [, cat] of Object.entries(BASELINE.categories)) {
|
||||
const matched = pages.filter((p) => matchGlob(cat.pattern, p));
|
||||
const count = matched.length;
|
||||
const status = count >= cat.min ? "✅" : "❌";
|
||||
if (count < cat.min) categoryFail = true;
|
||||
console.log(` ${status} ${cat.label}: ${count} (min ${cat.min})`);
|
||||
}
|
||||
console.log("");
|
||||
|
||||
// Total check
|
||||
const totalOk = total >= BASELINE.total;
|
||||
if (!totalOk) {
|
||||
console.log(`❌ Total ${total} < baseline ${BASELINE.total}`);
|
||||
}
|
||||
|
||||
// List all pages
|
||||
console.log("Pages:");
|
||||
for (const p of pages) {
|
||||
console.log(
|
||||
` /${p.replace(/\/page\.tsx$/, "").replace(/^page\.tsx$/, "")}`,
|
||||
);
|
||||
}
|
||||
console.log("");
|
||||
|
||||
if (!totalOk || categoryFail) {
|
||||
console.log("Result: FAIL");
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log(`Result: PASS (${total} pages, all categories meet minimum)`);
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
169
apps/portal-shell/scripts/check-route-table.ts
Normal file
169
apps/portal-shell/scripts/check-route-table.ts
Normal file
@@ -0,0 +1,169 @@
|
||||
// Route table consistency check (ARCHITECTURE.md §10 P1-8)
|
||||
//
|
||||
// Verifies that every actual /shell/* page.tsx route is registered in
|
||||
// route-permissions.ts (EXACT / PREFIX / DASHBOARD / PUBLIC_ROUTES).
|
||||
// Catches "unregistered routes" that would fall through to the catch-all
|
||||
// and be denied by middleware (fail-closed) — developers get a clear CI
|
||||
// error instead of a confusing runtime 403.
|
||||
//
|
||||
// Also reports "ghost entries" (EXACT table entries without a page.tsx)
|
||||
// as informational output — these are planned future routes (P2-P5).
|
||||
//
|
||||
// Usage: tsx scripts/check-route-table.ts
|
||||
// Exit: 0 = pass, 1 = violations found
|
||||
//
|
||||
// Related: ARCHITECTURE.md §3.4 V3-A1, §5.3, §10 P1-8, §11.7 红线 #5
|
||||
import * as fs from "node:fs";
|
||||
import * as path from "node:path";
|
||||
|
||||
const APP_DIR = path.resolve(process.cwd(), "src/app");
|
||||
const ROUTE_PERMS_FILE = path.resolve(
|
||||
process.cwd(),
|
||||
"src/shared/lib/route-permissions.ts",
|
||||
);
|
||||
|
||||
interface Violation {
|
||||
type: "unregistered_route" | "ghost_entry";
|
||||
route: string;
|
||||
detail: string;
|
||||
}
|
||||
|
||||
function scanActualRoutes(): Set<string> {
|
||||
const routes = new Set<string>();
|
||||
|
||||
function walk(dir: string, prefix: string): void {
|
||||
const entries = fs.readdirSync(dir, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
// Skip catch-all [[...route]] directory
|
||||
if (entry.name.startsWith("[[")) continue;
|
||||
walk(full, `${prefix}/${entry.name}`);
|
||||
} else if (entry.name === "page.tsx") {
|
||||
routes.add(prefix || "/");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
walk(APP_DIR, "");
|
||||
return routes;
|
||||
}
|
||||
|
||||
function extractRegisteredRoutes(): {
|
||||
exact: Set<string>;
|
||||
prefixes: string[];
|
||||
publicRoutes: Set<string>;
|
||||
} {
|
||||
const content = fs.readFileSync(ROUTE_PERMS_FILE, "utf8");
|
||||
const exact = new Set<string>();
|
||||
const prefixes: string[] = [];
|
||||
const publicRoutes = new Set<string>();
|
||||
|
||||
const routeKeyRe = new RegExp('"(/[^"]*?)":\\s*\\{', "g");
|
||||
const prefixRe = new RegExp('prefix:\\s*"(/[^"]*?)"', "g");
|
||||
|
||||
let m: RegExpExecArray | null;
|
||||
while ((m = routeKeyRe.exec(content)) !== null) {
|
||||
exact.add(m[1]);
|
||||
}
|
||||
while ((m = prefixRe.exec(content)) !== null) {
|
||||
prefixes.push(m[1]);
|
||||
}
|
||||
// PUBLIC_ROUTES array entries (skip past `readonly string[] =` to the real `[`)
|
||||
const publicBlock = content.match(
|
||||
new RegExp("PUBLIC_ROUTES[^=]*=\\s*\\[([\\s\\S]*?)\\]"),
|
||||
)?.[1];
|
||||
if (publicBlock) {
|
||||
const re = new RegExp('"(/[^"]*?)"', "g");
|
||||
while ((m = re.exec(publicBlock)) !== null) {
|
||||
publicRoutes.add(m[1]);
|
||||
}
|
||||
}
|
||||
|
||||
return { exact, prefixes, publicRoutes };
|
||||
}
|
||||
|
||||
function isRegistered(
|
||||
route: string,
|
||||
exact: Set<string>,
|
||||
prefixes: string[],
|
||||
publicRoutes: Set<string>,
|
||||
): boolean {
|
||||
if (publicRoutes.has(route)) return true;
|
||||
if (exact.has(route)) return true;
|
||||
for (const p of prefixes) {
|
||||
if (route.startsWith(p)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function main(): void {
|
||||
const actualRoutes = scanActualRoutes();
|
||||
const { exact, prefixes, publicRoutes } = extractRegisteredRoutes();
|
||||
|
||||
const violations: Violation[] = [];
|
||||
|
||||
// Check A: every actual /shell/* route must be registered
|
||||
for (const route of [...actualRoutes].sort()) {
|
||||
if (!route.startsWith("/shell")) continue;
|
||||
if (!isRegistered(route, exact, prefixes, publicRoutes)) {
|
||||
violations.push({
|
||||
type: "unregistered_route",
|
||||
route,
|
||||
detail:
|
||||
"page.tsx exists but route not in EXACT/PREFIX/DASHBOARD/PUBLIC_ROUTES",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Check B (informational): ghost entries (EXACT entries without page.tsx)
|
||||
const ghostEntries: string[] = [];
|
||||
for (const entry of [...exact].sort()) {
|
||||
if (!entry.startsWith("/shell/")) continue;
|
||||
if (!actualRoutes.has(entry)) {
|
||||
ghostEntries.push(entry);
|
||||
}
|
||||
}
|
||||
|
||||
// Report
|
||||
console.log("=== Route Table Consistency Check ===");
|
||||
console.log(
|
||||
`Actual /shell/* routes: ${[...actualRoutes].filter((r) => r.startsWith("/shell")).length}`,
|
||||
);
|
||||
console.log(
|
||||
`EXACT entries: ${[...exact].filter((r) => r.startsWith("/shell/")).length}`,
|
||||
);
|
||||
console.log(`PREFIX entries: ${prefixes.length}`);
|
||||
console.log(`PUBLIC_ROUTES: ${publicRoutes.size}`);
|
||||
console.log("");
|
||||
|
||||
if (violations.length > 0) {
|
||||
console.log("❌ VIOLATIONS (unregistered routes):");
|
||||
for (const v of violations) {
|
||||
console.log(` ${v.route} — ${v.detail}`);
|
||||
}
|
||||
console.log("");
|
||||
}
|
||||
|
||||
if (ghostEntries.length > 0) {
|
||||
console.log(
|
||||
`ℹ️ GHOST ENTRIES (planned, no page.tsx yet): ${ghostEntries.length}`,
|
||||
);
|
||||
for (const g of ghostEntries) {
|
||||
console.log(` ${g}`);
|
||||
}
|
||||
console.log("");
|
||||
}
|
||||
|
||||
if (violations.length > 0) {
|
||||
console.log(`Result: FAIL (${violations.length} violation(s))`);
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log(
|
||||
`Result: PASS (0 violations, ${ghostEntries.length} ghost entries)`,
|
||||
);
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
Reference in New Issue
Block a user