configuration/principle/data/metaprogramming.data.json
configuration/principle/data/metaprogramming.data.json is a file in GovLab Context. 387 lines of code and 0 definitions.
{
"category": "Metaprogramming / Language-Oriented Architecture",
"check": {
"population": "every generator, reflective access, evaluation site and language definition in the codebase",
"freshness": "a verdict stands until a generator, a grammar or the model it generates from changes",
"refusal": "the banned-API rule, the generator test or the grammar validation fails the change",
"observation": "eval and reflection call sites read from source, and generated output compared with its model",
"evidence": "none: the catalog states this check as a class, so a watched run belongs to each system that adopts it",
"authority": "the model and the grammar, which generated output is derived from and compared against"
},
"records": [
{
"id": "homoiconicity",
"distinctFrom": [
{
"id": "lexicon:readability",
"reason": "Homoiconicity is programs held as data, while readability is how easily the developer reads the source that results."
}
],
"name": "Homoiconicity",
"definition": "The degree to which a language represents its programs in its own data structures, so programs can be inspected and transformed as data.",
"canon": ["homoiconicity"],
"type": "quality-attribute",
"scope": [
"language",
"metaprogramming"
],
"requires": ["Code-as-Data Representation"],
"reinforces": ["Metaprogramming"],
"enables": [
"Macro Systems",
"DSLs"
],
"conflicts_with": ["Opaque Syntax Trees"],
"tensions_with": ["Readability"],
"violated_by": ["lexicon:string-based-code-generation"],
"detected_by": ["language capability check"],
"measured_by": ["macro/code-as-data usage"],
"refactored_by": ["lexicon:syntax-tree-generation"],
"enforced_by": ["language/tooling constraints"],
"severity": "contextual",
"exemplar": {
"before": "function evaluateFoo(foo: Foo) { return foo.value * 2; }\nconst fooRule = { operation: \"multiply\", operand: 2 };",
"after": "type Expr =\n | { op: \"value\"; key: keyof Foo }\n | { op: \"const\"; value: number }\n | { op: \"multiply\"; left: Expr; right: Expr };\nconst fooRule: Expr = { op: \"multiply\", left: { op: \"value\", key: \"value\" }, right: { op: \"const\", value: 2 } };\nconst result = evaluate(fooRule, foo);",
"lang": "ts"
}
},
{
"id": "code-as-data",
"name": "Code as Data",
"definition": "A design rule that logic to be generated or transformed is held as a typed data structure, such as a syntax tree, that tools can inspect and rewrite.",
"type": "principle",
"scope": [
"language",
"compiler",
"runtime"
],
"requires": ["AST or Data Representation"],
"reinforces": [
"Homoiconicity",
"Code Generation"
],
"enables": ["Program Transformation"],
"conflicts_with": ["String-Based Code Generation"],
"tensions_with": ["Safety/Debuggability"],
"violated_by": ["lexicon:unchecked-dynamic-code"],
"detected_by": ["dynamic eval/string code construction"],
"measured_by": ["unsafe eval count"],
"refactored_by": [
"lexicon:syntax-tree-generation",
"architecture:domain-specific-language"
],
"enforced_by": ["banned API rules"],
"severity": "contextual",
"exemplar": {
"before": "function fooRule(foo: Foo) { return foo.count > 3 && foo.active; }",
"after": "const fooRule = {\n op: \"and\",\n args: [\n { op: \"gt\", field: \"count\", value: 3 },\n { op: \"eq\", field: \"active\", value: true },\n ],\n} as const;\nexecuteRule(fooRule, foo);",
"lang": "ts"
}
},
{
"id": "metaprogramming",
"distinctFrom": [
{
"id": "lexicon:dsls",
"reason": "Metaprogramming is code that writes or transforms code, while a domain-specific language is a notation for one domain, which metaprogramming can build."
}
],
"name": "Metaprogramming",
"definition": "A technique for writing programs that generate or transform other programs, at compile time or at runtime.",
"type": "technique",
"scope": [
"compile-time",
"runtime",
"framework"
],
"requires": ["Reflection/AST/Code Generation"],
"reinforces": [
"DRY",
"DSLs"
],
"enables": ["Boilerplate Elimination"],
"conflicts_with": [],
"tensions_with": [
"Debuggability",
"Static Analysis",
"Explicit Handwritten Code"
],
"violated_by": ["lexicon:unchecked-dynamic-code"],
"detected_by": ["dynamic generation without tests/schema"],
"measured_by": [
"generated code coverage",
"complexity"
],
"refactored_by": [
"lexicon:unit-tests",
"lexicon:declare-capability"
],
"enforced_by": ["generator validation"],
"severity": "contextual",
"exemplar": {
"before": "class FooDto { id!: string; name!: string; }\nclass BarDto { id!: string; name!: string; }",
"after": "const entity = defineEntity({ id: string(), name: string() });\nconst FooDto = generateType(\"FooDto\", entity);\nconst BarDto = generateType(\"BarDto\", entity);",
"lang": "ts"
}
},
{
"id": "reflection",
"distinctFrom": [
{
"id": "architecture:dynamic-binding",
"reason": "Reflection reads type metadata at runtime, while dynamic binding selects an implementation at runtime, with or without reflection."
},
{
"id": "architecture:introspection",
"reason": "Introspection only reads a type and its members, while reflection also acts on what it reads."
},
{
"id": "architecture:static-analysis",
"reason": "Reflection inspects structure while the program runs, while static analysis inspects source without running it."
}
],
"name": "Reflection",
"definition": "A mechanism that lets a program read and act on type metadata about its own structure at runtime.",
"type": "mechanism",
"scope": [
"runtime",
"metadata",
"framework"
],
"requires": ["Runtime Type Metadata"],
"reinforces": [
"Introspection",
"Runtime Discovery"
],
"enables": ["Dynamic Binding"],
"conflicts_with": [],
"tensions_with": [
"Performance/Safety",
"Static Analysis"
],
"violated_by": ["lexicon:reflective-contract-bypass"],
"detected_by": ["reflective access to internals"],
"measured_by": ["unsafe reflection count"],
"refactored_by": ["lexicon:declare-capability"],
"enforced_by": ["lint/security rules"],
"severity": "contextual",
"exemplar": {
"before": "const fields = [\"id\", \"name\", \"count\"];\nfor (const field of fields) renderField(foo[field]);",
"after": "for (const [field, metadata] of reflect(FooSchema).entries()) {\n renderField(field, metadata, foo[field]);\n}",
"lang": "ts"
}
},
{
"id": "introspection",
"name": "Introspection",
"definition": "A mechanism that lets a program query an object's type and public members at runtime without changing them.",
"type": "mechanism",
"scope": [
"runtime",
"metadata"
],
"requires": ["Type Metadata"],
"reinforces": ["Self-Describing Systems"],
"enables": [
"Discovery",
"Diagnostics"
],
"conflicts_with": [
"Opaque Runtime",
"Opaque Runtime Behavior"
],
"tensions_with": ["Encapsulation"],
"violated_by": ["lexicon:exposed-internals"],
"detected_by": ["introspection of private internals"],
"measured_by": ["introspection usage risk"],
"refactored_by": ["lexicon:declare-capability"],
"enforced_by": ["API boundaries"],
"severity": "contextual",
"exemplar": {
"before": "function supportsExport(plugin: any) {\n try { plugin.exportFoo(foo); return true; } catch { return false; }\n}",
"after": "function supportsExport(plugin: Plugin) {\n return introspect(plugin).methods.includes(\"exportFoo\");\n}",
"lang": "ts"
}
},
{
"id": "compile-time-evaluation",
"name": "Compile-Time Evaluation",
"definition": "A mechanism that computes values, checks or generated code during the build, so the work and its errors happen before runtime.",
"type": "mechanism",
"scope": [
"compiler",
"build"
],
"requires": ["Compile-Time Inputs"],
"reinforces": [
"Optimization",
"Type Safety"
],
"enables": ["Early Error Detection"],
"conflicts_with": [],
"tensions_with": [
"Build Complexity",
"Runtime Dynamic Evaluation"
],
"violated_by": ["lexicon:deferred-static-check"],
"detected_by": ["repeated runtime reflection/validation"],
"measured_by": ["compile-time coverage"],
"refactored_by": [],
"enforced_by": ["compiler plugins/build checks"],
"severity": "contextual",
"exemplar": {
"before": "const fooRoutes = buildRoutesAtStartup(fooRouteDefinitions);",
"after": "const fooRoutes = compileTime(() => buildRoutes(fooRouteDefinitions));\nexport const routeTable = fooRoutes;",
"lang": "ts"
}
},
{
"id": "runtime-code-generation",
"name": "Runtime Code Generation",
"definition": "A mechanism that builds executable code while the program runs, from a specification such as a field mapping.",
"type": "mechanism",
"scope": [
"runtime",
"framework"
],
"requires": ["Safe Generation Boundary"],
"reinforces": ["Runtime Extensibility"],
"enables": ["Dynamic Optimization/Adaptation"],
"conflicts_with": [],
"tensions_with": [
"Security/Debugging",
"Static Safety"
],
"violated_by": ["lexicon:unchecked-dynamic-code"],
"detected_by": ["dynamic eval with external input"],
"measured_by": ["unsafe generation paths"],
"refactored_by": [
"lexicon:syntax-tree-generation",
"lexicon:sandboxing",
"architecture:compile-time-evaluation"
],
"enforced_by": ["security policy"],
"severity": "discouraged",
"exemplar": {
"before": "function mapFoo(row: any) {\n return { id: row[\"foo_id\"], name: row[\"foo_name\"], count: row[\"foo_count\"] };\n}",
"after": "const mapFoo = generateMapper<FooRow, Foo>({\n foo_id: \"id\",\n foo_name: \"name\",\n foo_count: \"count\",\n});",
"lang": "ts"
}
},
{
"id": "domain-specific-language",
"name": "Domain-Specific Language (DSL)",
"definition": "A design pattern that expresses a domain's rules or workflows in a small language with a defined grammar and a validator.",
"type": "pattern",
"scope": [
"domain",
"configuration",
"rules"
],
"requires": ["Formal Grammar/Semantics"],
"reinforces": [
"Declarative Configuration",
"Ubiquitous Language"
],
"enables": ["Domain Expressiveness"],
"conflicts_with": ["General-Purpose Boilerplate"],
"tensions_with": ["Tooling/Maintenance"],
"violated_by": ["lexicon:ad-hoc-mini-language"],
"detected_by": ["stringly-typed rules without parser/schema"],
"measured_by": ["DSL validation coverage"],
"refactored_by": ["lexicon:validate-at-the-boundary"],
"enforced_by": [
"DSL tests",
"schema/grammar checks"
],
"severity": "contextual",
"exemplar": {
"before": "createWorkflow([\n { type: \"validate\", target: \"foo\" },\n { type: \"save\", target: \"foo\" },\n { type: \"publish\", target: \"foo.created\" },\n]);",
"after": "fooWorkflow(\"create\", flow =>\n flow.validate(FooSchema)\n .save(\"FooStore\")\n .publish(\"FooCreated\")\n);",
"lang": "ts"
}
},
{
"id": "language-oriented-programming",
"distinctFrom": [
{
"id": "lexicon:one-size-general-purpose-code",
"reason": "Language-oriented programming gives each domain its own language, while general-purpose code writes every domain in one language."
}
],
"name": "Language-Oriented Programming",
"definition": "An approach in which each problem domain gets its own language, with a type checker and an evaluator, and solutions are written in it.",
"type": "approach",
"scope": [
"domain",
"platform",
"code generation"
],
"requires": [
"DSLs",
"Code Generation or Interpreters"
],
"reinforces": ["Domain Modeling"],
"enables": ["High-Level Domain Expression"],
"conflicts_with": [],
"tensions_with": [
"Toolchain Complexity",
"One-Size General-Purpose Code"
],
"violated_by": ["lexicon:ad-hoc-mini-language"],
"detected_by": ["multiple inconsistent rule/config syntaxes"],
"measured_by": ["language consistency/tooling"],
"refactored_by": [
"architecture:domain-specific-language",
"lexicon:automated-enforcement"
],
"enforced_by": ["grammar/schema validation"],
"severity": "contextual",
"exemplar": {
"before": "function processFoo(config: Record<string, unknown>) {\n interpretAdHocConfig(config);\n}",
"after": "const FooPolicyLanguage = defineLanguage({\n expressions: [\"field\", \"equals\", \"all\", \"any\"],\n typeChecker: fooPolicyTypeChecker,\n evaluator: fooPolicyEvaluator,\n});\nFooPolicyLanguage.run(fooPolicy, foo);",
"lang": "ts"
}
},
{
"id": "model-driven-architecture",
"distinctFrom": [
{
"id": "architecture:metadata-driven-design",
"reason": "Model-driven architecture generates the implementation from a formal model by transformation rules, while metadata-driven design drives forms, routes or plugins from validated metadata."
}
],
"name": "Model-Driven Architecture",
"aliases": ["MDA"],
"definition": "An approach in which a formal model is the source of truth and the implementation is generated from it by transformation rules.",
"type": "approach",
"scope": [
"system",
"code generation",
"domain model"
],
"requires": [
"Formal Model",
"Transformation Rules"
],
"reinforces": ["Metadata-Driven Design"],
"enables": ["Generated Implementations"],
"conflicts_with": ["Handwritten Divergence"],
"tensions_with": [],
"violated_by": ["lexicon:handwritten-divergence"],
"detected_by": ["model-code drift"],
"measured_by": ["generation conformance"],
"refactored_by": [
"lexicon:code-generation",
"architecture:model-evaluation"
],
"enforced_by": ["generation CI"],
"severity": "contextual",
"exemplar": {
"before": "class FooController {}\nclass FooService {}\nclass FooRepository {}\nclass FooDto {}",
"after": "const fooModel = defineModel({\n entity: \"Foo\",\n fields: { id: \"FooId\", name: \"string\" },\n operations: [\"create\", \"read\", \"rename\"],\n});\ngenerateApplication(fooModel);",
"lang": "ts"
}
}
]
}