mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-01 17:39:39 +02:00
392 lines
14 KiB
TypeScript
392 lines
14 KiB
TypeScript
/**
|
||
* Effect-native law enforcement for the TrustGraph TS port.
|
||
*
|
||
* Encodes the adapted beep-effect effect-first/schema-first laws as regex and
|
||
* AST sweeps over packages/*\/src and scripts/, with a ratcheting baseline:
|
||
* every violation must be covered by an exact-count baseline entry or a
|
||
* reasoned permanent exemption in scripts/effect-laws.allowlist.json. Counts
|
||
* that drop force a baseline update (ratchet down); counts that grow fail.
|
||
*
|
||
* Usage:
|
||
* bun scripts/check-effect-laws.ts # verify, exit 1 on drift
|
||
* bun scripts/check-effect-laws.ts --write-baseline # regenerate baseline section
|
||
*/
|
||
|
||
import * as BunFileSystem from "@effect/platform-bun/BunFileSystem";
|
||
import * as BunRuntime from "@effect/platform-bun/BunRuntime";
|
||
import { Effect } from "effect";
|
||
import * as A from "effect/Array";
|
||
import * as Console from "effect/Console";
|
||
import * as FileSystem from "effect/FileSystem";
|
||
import * as O from "effect/Option";
|
||
import * as S from "effect/Schema";
|
||
import * as Str from "effect/String";
|
||
import ts from "typescript";
|
||
|
||
const ALLOWLIST_PATH = "scripts/effect-laws.allowlist.json";
|
||
const SELF_PATH = "scripts/check-effect-laws.ts";
|
||
|
||
class LawCheckFailed extends S.TaggedErrorClass<LawCheckFailed>()(
|
||
"LawCheckFailed",
|
||
{ message: S.String },
|
||
) {}
|
||
|
||
class BaselineEntry extends S.Class<BaselineEntry>("BaselineEntry")({
|
||
rule: S.String,
|
||
path: S.String,
|
||
count: S.Number,
|
||
}) {}
|
||
|
||
class Exemption extends S.Class<Exemption>("Exemption")({
|
||
rule: S.String,
|
||
path: S.String,
|
||
reason: S.String,
|
||
}) {}
|
||
|
||
class Allowlist extends S.Class<Allowlist>("Allowlist")({
|
||
exemptions: S.Array(Exemption),
|
||
baseline: S.Array(BaselineEntry),
|
||
}) {}
|
||
|
||
const AllowlistJson = S.fromJsonString(Allowlist);
|
||
const decodeAllowlist = S.decodeUnknownEffect(AllowlistJson);
|
||
const encodeAllowlist = S.encodeUnknownEffect(AllowlistJson);
|
||
|
||
type RuleScope = "prod" | "all";
|
||
|
||
interface RegexRule {
|
||
readonly id: string;
|
||
readonly description: string;
|
||
readonly scope: RuleScope;
|
||
readonly pattern: RegExp;
|
||
}
|
||
|
||
interface Violation {
|
||
readonly rule: string;
|
||
readonly path: string;
|
||
readonly line: number;
|
||
readonly excerpt: string;
|
||
}
|
||
|
||
const regexRules: ReadonlyArray<RegexRule> = [
|
||
{
|
||
id: "no-native-json",
|
||
description: "Use Schema JSON codecs (S.fromJsonString / S.UnknownFromJsonString), not native JSON",
|
||
scope: "all",
|
||
pattern: /JSON\.(parse|stringify)\(/,
|
||
},
|
||
{
|
||
id: "no-process-env",
|
||
description: "Read configuration through Config / ConfigProvider, not process.env",
|
||
scope: "all",
|
||
pattern: /process\.env/,
|
||
},
|
||
{
|
||
id: "no-error-throw",
|
||
description: "Fail with tagged errors on the Effect channel, not thrown native Error",
|
||
scope: "all",
|
||
pattern: /\bthrow\s+new\s|\bnew Error\(/,
|
||
},
|
||
{
|
||
id: "no-native-switch",
|
||
description: "Branch with effect/Match or schema tagged-union matchers, not native switch",
|
||
scope: "all",
|
||
pattern: /\bswitch\s*\(/,
|
||
},
|
||
{
|
||
id: "no-native-sort",
|
||
description: "Sort with A.sort and an explicit Order, not Array.prototype.sort",
|
||
scope: "all",
|
||
pattern: /\.sort\(\s*[)(]/,
|
||
},
|
||
{
|
||
id: "no-effect-run",
|
||
description: "Run effects only at process/test boundaries (runMain); libraries return Effect",
|
||
scope: "all",
|
||
pattern: /Effect\.run(Sync|Promise|Fork)\b/,
|
||
},
|
||
{
|
||
id: "no-schema-suffix",
|
||
description: "Schema constants carry the domain name, never a Schema suffix",
|
||
scope: "all",
|
||
pattern: /export const \w+Schema\b/,
|
||
},
|
||
{
|
||
id: "no-node-fs-path",
|
||
description: "Use effect/FileSystem and effect/Path services, not node:fs / node:path",
|
||
scope: "all",
|
||
pattern: /from\s+"node:(fs|path)"/,
|
||
},
|
||
{
|
||
id: "no-native-fetch",
|
||
description: "Use HttpClient from effect/unstable/http with a platform layer, not fetch",
|
||
scope: "all",
|
||
pattern: /\bfetch\s*\(/,
|
||
},
|
||
{
|
||
id: "no-ts-escape",
|
||
description: "No any/test-escape hatches in source",
|
||
scope: "all",
|
||
pattern: /@ts-ignore|@ts-expect-error|\bas any\b/,
|
||
},
|
||
{
|
||
id: "no-native-timers",
|
||
description: "Model time with Effect.sleep / Schedule / Duration, not setTimeout/setInterval",
|
||
scope: "all",
|
||
pattern: /\bset(Timeout|Interval)\(/,
|
||
},
|
||
];
|
||
|
||
const SCHEMA_FIRST_RULE = "schema-first-data";
|
||
|
||
const sourceFilePattern = /\.tsx?$/;
|
||
|
||
const isExcludedDir = (segment: string): boolean =>
|
||
segment === "dist" || segment === "node_modules" || segment === ".turbo" || segment === "__tests__";
|
||
|
||
const isTestFile = (path: string): boolean =>
|
||
path.includes("/__tests__/") ||
|
||
/\.(test|spec)\.tsx?$/.test(path);
|
||
|
||
const isProdSource = (path: string): boolean =>
|
||
path.startsWith("packages/") && path.includes("/src/") && !isTestFile(path);
|
||
|
||
const isScriptSource = (path: string): boolean => path.startsWith("scripts/");
|
||
|
||
const collectSourceFiles = Effect.fn("LawCheck.collectSourceFiles")(function* (
|
||
fs: FileSystem.FileSystem,
|
||
) {
|
||
const entries = yield* fs.readDirectory(".", { recursive: true });
|
||
return A.filter(
|
||
entries,
|
||
(path) =>
|
||
sourceFilePattern.test(path) &&
|
||
!path.endsWith(".d.ts") &&
|
||
path !== SELF_PATH &&
|
||
!A.some(path.split("/"), isExcludedDir) &&
|
||
!isTestFile(path) &&
|
||
(isProdSource(path) || isScriptSource(path)),
|
||
);
|
||
});
|
||
|
||
const scanRegexRules = (path: string, text: string): ReadonlyArray<Violation> => {
|
||
const prod = isProdSource(path);
|
||
const lines = text.split("\n");
|
||
return regexRules
|
||
.filter((rule) => rule.scope === "all" || prod)
|
||
.flatMap((rule) =>
|
||
lines.flatMap((lineText, index) =>
|
||
rule.pattern.test(lineText)
|
||
? [{
|
||
rule: rule.id,
|
||
path,
|
||
line: index + 1,
|
||
excerpt: Str.trim(lineText).slice(0, 120),
|
||
}]
|
||
: [],
|
||
),
|
||
);
|
||
};
|
||
|
||
/**
|
||
* Law 38/39 split: an exported interface or type literal whose members are all
|
||
* non-function property signatures is a pure-data model and must be a Schema.
|
||
* Members with call/method/construct/index signatures or function-typed
|
||
* properties mark a service contract, which may stay an interface.
|
||
*/
|
||
const scanSchemaFirst = (path: string, text: string): ReadonlyArray<Violation> => {
|
||
if (!isProdSource(path) || path.endsWith(".tsx")) return [];
|
||
|
||
const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
|
||
const violations: Violation[] = [];
|
||
|
||
const isExported = (node: ts.HasModifiers): boolean =>
|
||
ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
|
||
|
||
// A same-name const (schema value + type merge, e.g. recursive S.suspend
|
||
// schemas) means the schema already exists; the companion type is required.
|
||
const constNames = new Set<string>();
|
||
for (const statement of source.statements) {
|
||
if (ts.isVariableStatement(statement)) {
|
||
for (const declaration of statement.declarationList.declarations) {
|
||
if (ts.isIdentifier(declaration.name)) constNames.add(declaration.name.text);
|
||
}
|
||
}
|
||
}
|
||
|
||
const isFunctionType = (type: ts.TypeNode | undefined): boolean =>
|
||
type !== undefined && (ts.isFunctionTypeNode(type) || ts.isConstructorTypeNode(type));
|
||
|
||
// Capability-typed members (Effects, Streams, schema codecs, layers,
|
||
// backends/services) mark a contract, not a data model.
|
||
const capabilityTypePattern =
|
||
/\b(Effect|Stream|Layer|Scope|Fiber|Queue|PubSub|Deferred|Ref|SubscriptionRef|SynchronizedRef|Codec|Schema|Context|Runtime)\s*[.<]|\b\w*(Backend|Service|Producer|Consumer|Requestor|Client|Factory|RequestResponse)\b/;
|
||
|
||
const isCapabilityType = (type: ts.TypeNode | undefined): boolean =>
|
||
type !== undefined && capabilityTypePattern.test(type.getText(source));
|
||
|
||
const isPureDataMembers = (members: ts.NodeArray<ts.TypeElement>): boolean =>
|
||
members.length > 0 &&
|
||
members.every(
|
||
(member) =>
|
||
ts.isPropertySignature(member) &&
|
||
!isFunctionType(member.type) &&
|
||
!isCapabilityType(member.type),
|
||
);
|
||
|
||
// Schemas cannot be generic; generic shapes stay structural types.
|
||
const isGeneric = (typeParameters: ts.NodeArray<ts.TypeParameterDeclaration> | undefined): boolean =>
|
||
typeParameters !== undefined && typeParameters.length > 0;
|
||
|
||
// Law 38/39 split: constructor/function option bags stay interfaces.
|
||
const isOptionBagName = (name: string): boolean => /Options$/.test(name);
|
||
|
||
const record = (node: ts.Node, name: string): void => {
|
||
const position = source.getLineAndCharacterOfPosition(node.getStart(source));
|
||
violations.push({
|
||
rule: SCHEMA_FIRST_RULE,
|
||
path,
|
||
line: position.line + 1,
|
||
excerpt: `exported pure-data shape ${name} should be an effect/Schema model`,
|
||
});
|
||
};
|
||
|
||
const visit = (node: ts.Node): void => {
|
||
if (
|
||
ts.isInterfaceDeclaration(node) &&
|
||
isExported(node) &&
|
||
!isGeneric(node.typeParameters) &&
|
||
node.heritageClauses === undefined &&
|
||
isPureDataMembers(node.members) &&
|
||
!constNames.has(node.name.text) &&
|
||
!isOptionBagName(node.name.text)
|
||
) {
|
||
record(node, node.name.text);
|
||
}
|
||
if (
|
||
ts.isTypeAliasDeclaration(node) &&
|
||
isExported(node) &&
|
||
!isGeneric(node.typeParameters) &&
|
||
ts.isTypeLiteralNode(node.type) &&
|
||
isPureDataMembers(node.type.members) &&
|
||
!constNames.has(node.name.text) &&
|
||
!isOptionBagName(node.name.text)
|
||
) {
|
||
record(node, node.name.text);
|
||
}
|
||
ts.forEachChild(node, visit);
|
||
};
|
||
|
||
visit(source);
|
||
return violations;
|
||
};
|
||
|
||
const countKey = (rule: string, path: string): string => `${rule} ${path}`;
|
||
|
||
const loadAllowlist = Effect.fn("LawCheck.loadAllowlist")(function* (
|
||
fs: FileSystem.FileSystem,
|
||
) {
|
||
const exists = yield* fs.exists(ALLOWLIST_PATH);
|
||
if (!exists) {
|
||
return Allowlist.make({ exemptions: [], baseline: [] });
|
||
}
|
||
const raw = yield* fs.readFileString(ALLOWLIST_PATH);
|
||
return yield* decodeAllowlist(raw).pipe(
|
||
Effect.mapError((cause) =>
|
||
new LawCheckFailed({ message: `Invalid allowlist at ${ALLOWLIST_PATH}: ${cause.message}` }),
|
||
),
|
||
);
|
||
});
|
||
|
||
const program = Effect.gen(function* () {
|
||
const fs = yield* FileSystem.FileSystem;
|
||
const writeBaseline = A.contains(Bun.argv, "--write-baseline");
|
||
|
||
const files = yield* collectSourceFiles(fs);
|
||
const violations: Violation[] = [];
|
||
for (const path of files) {
|
||
const text = yield* fs.readFileString(path);
|
||
violations.push(...scanRegexRules(path, text));
|
||
violations.push(...scanSchemaFirst(path, text));
|
||
}
|
||
|
||
const listFilter = A.findFirst(Bun.argv, (arg) => arg.startsWith("--list"));
|
||
if (O.isSome(listFilter)) {
|
||
const ruleFilter = listFilter.value.includes("=") ? listFilter.value.split("=")[1] : undefined;
|
||
const matching = violations.filter((violation) => ruleFilter === undefined || violation.rule === ruleFilter);
|
||
for (const violation of matching) {
|
||
yield* Console.log(`${violation.path}:${violation.line} [${violation.rule}] ${violation.excerpt}`);
|
||
}
|
||
yield* Console.log(`${matching.length} finding(s).`);
|
||
return;
|
||
}
|
||
|
||
const allowlist = yield* loadAllowlist(fs);
|
||
|
||
const exemptionKeys = new Set(
|
||
allowlist.exemptions.map((entry) => countKey(entry.rule, entry.path)),
|
||
);
|
||
const counted = new Map<string, { rule: string; path: string; count: number; samples: Violation[] }>();
|
||
for (const violation of violations) {
|
||
const key = countKey(violation.rule, violation.path);
|
||
if (exemptionKeys.has(key)) continue;
|
||
const existing = counted.get(key) ?? { rule: violation.rule, path: violation.path, count: 0, samples: [] };
|
||
existing.count += 1;
|
||
if (existing.samples.length < 3) existing.samples.push(violation);
|
||
counted.set(key, existing);
|
||
}
|
||
|
||
if (writeBaseline) {
|
||
const baseline = A.sort(
|
||
[...counted.values()].map(({ rule, path, count }) => BaselineEntry.make({ rule, path, count })),
|
||
(left: BaselineEntry, right: BaselineEntry) =>
|
||
left.rule < right.rule ? -1 : left.rule > right.rule ? 1 :
|
||
left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
|
||
);
|
||
const next = Allowlist.make({ exemptions: allowlist.exemptions, baseline });
|
||
const encoded = yield* encodeAllowlist(next).pipe(
|
||
Effect.mapError((cause) => new LawCheckFailed({ message: `Failed to encode allowlist: ${cause.message}` })),
|
||
);
|
||
yield* fs.writeFileString(ALLOWLIST_PATH, `${encoded}\n`);
|
||
yield* Console.log(`Baseline written: ${baseline.length} entries covering ${violations.length} findings.`);
|
||
return;
|
||
}
|
||
|
||
const baselineByKey = new Map(
|
||
allowlist.baseline.map((entry) => [countKey(entry.rule, entry.path), entry] as const),
|
||
);
|
||
|
||
const failures: string[] = [];
|
||
for (const { rule, path, count, samples } of counted.values()) {
|
||
const allowed = O.fromUndefinedOr(baselineByKey.get(countKey(rule, path)));
|
||
const max = O.match(allowed, { onNone: () => 0, onSome: (entry) => entry.count });
|
||
if (count > max) {
|
||
const detail = samples
|
||
.map((sample) => ` ${sample.path}:${sample.line} ${sample.excerpt}`)
|
||
.join("\n");
|
||
failures.push(` [${rule}] ${path}: ${count} found, ${max} allowed\n${detail}`);
|
||
}
|
||
}
|
||
|
||
for (const entry of allowlist.baseline) {
|
||
const live = counted.get(countKey(entry.rule, entry.path));
|
||
const count = live?.count ?? 0;
|
||
if (count < entry.count) {
|
||
failures.push(
|
||
` [stale-baseline] ${entry.path} [${entry.rule}]: baseline allows ${entry.count} but only ${count} remain — ratchet down with --write-baseline`,
|
||
);
|
||
}
|
||
}
|
||
|
||
if (failures.length > 0) {
|
||
yield* Console.error(`Effect law violations:\n${failures.join("\n")}`);
|
||
return yield* Effect.fail(new LawCheckFailed({ message: `${failures.length} law-check failure(s)` }));
|
||
}
|
||
|
||
const baselineTotal = allowlist.baseline.reduce((sum, entry) => sum + entry.count, 0);
|
||
yield* Console.log(
|
||
`Effect laws clean: ${files.length} files checked, baseline debt ${baselineTotal} across ${allowlist.baseline.length} entries, ${allowlist.exemptions.length} documented exemptions.`,
|
||
);
|
||
}).pipe(Effect.provide(BunFileSystem.layer));
|
||
|
||
BunRuntime.runMain(program);
|