counterfact 0.11.0 → 0.12.0

package/.eslintrc.cjs

@@ -36,7 +36,14 @@ const rules = {
 };
 
 module.exports = {
-  ignorePatterns: ["/node_modules/", "/coverage/", "/reports/", "/out/"],
+  ignorePatterns: [
+    "/node_modules/",
+    "/coverage/",
+    "/reports/",
+    "/out/",
+    "_includes",
+    ".stryker-tmp",
+  ],
 
   extends: ["hardcore", "hardcore/ts", "hardcore/node"],
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # counterfact
 
+## 0.12.0
+
+### Minor Changes
+
+- 1a622d2: a REPL allows you to interact with the server's context programatically
+
 ## 0.11.0
 
 ### Minor Changes

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+## Where I need help
+
+- **Feedback:** First and foremost, send me feedback. What makes sense? What's confusing? What's missing? What's broken? [Send me an email](pmcelhaney@gmail.com), [open an issue](https://github.com/pmcelhaney/counterfact/issues/new), or [start a discussion](https://github.com/pmcelhaney/counterfact/discussions).
+- **Documentation:** There are probably typos in this very document. Please send PRs, large and small. You can do it right from your browser. If you're viewing this document in Github, click the pencil button in the top right corner.
+- **Graphic design:** I'm terrible at graphic design. I know good design when I see it, and I can tell you why it's good, but struggle with the creative process. Whether it's building a web site, designing a logo, brainstorming on a GUI, or fixing up some ugly Markdown code, I'll take whatever help I can get!
+- **Tests:** Test coverage is pretty good, but there are gaps. Filling those gaps is an easy way to gain some familiarity with the codebase.
+- **Code Generation:** As of this writing, the code that writes the code works okay, but it's kind of sloppy. Instead of printing strings of source code directly, I'd like to refactor everything to build ASTs. I'd also like to bring in [json-schema-to-typescript](https://github.com/bcherny/json-schema-to-typescript), which is more accurate than my hand-rolled MVP.
+- **Convert to TypeScript**: While Counterfact generates and runs TypeScript, ironically the code itself is in JavaScript. That's partly because running the unit tests in Jest requires [--experimental-vm-modules](https://jestjs.io/docs/ecmascript-modules). Getting Jest working with that and TypeScript at the same time was too much trouble when the project was getting off the ground.
+- **New features and bug fixes:** See the [issues list](https://github.com/pmcelhaney/counterfact/issues). If you plan on working on something, please add a comment and/or assign yourself.
+- **Spread the word!** If you find this project useful, please let others know about it. Share it in your team Slack, on social media, etc.
+
+## Development
+
+This is a pretty straightforward NodeJS project.
+
+```sh
+git clone git@github.com:pmcelhaney/counterfact.git
+cd counterfact
+npm install
+npm lint
+npm test
+```
+
+The [code generator](./src/typescript-generator/README.md) is under `src/typescript-generator`. The server is directly under `src`. I'm planning to move it to `src/server`.
+
+Testing and linting changes is important, but at this point I'm more concerned about changing the word "I" in this page to "we", so don't hesitate to create a PR, even it's not "finished".
+
+Thanks in advance!

package/README.md

@@ -1,24 +1,21 @@
-<div align="right">
 
-[![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpmcelhaney%2Fcounterfact%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/pmcelhaney/counterfact/main) ![MIT License](https://img.shields.io/badge/license-MIT-blue)
-
-</div>
 
-<div align="center">
+<div align="center" markdown="1">
 
 # Counterfact
 
 _Front end development without back end headaches_
 
-</div>
+[Quick Start](#quick-start) | [Documentation](./docs/usage.md) | [Contributing](CONTRIBUTING.md)
+
+Counterfact is a stand-in REST server powered by Node, TypeScript, and OpenAPI.<br>
+It enables you to write front end code and test UX flows without a complete back end.
 
-<div align="center">
-Counterfact is a stand-in REST server powered by Node, TypeScript, and OpenAPI.<br>Write front end code and test the user experience without a complete back end.
 </div>
 
 <br>
 
-<table align="center" cols="2">
+<table align="center" cols="2"  markdown="1">
 
 <tr>
 <td>
@@ -41,9 +38,16 @@ Counterfact is a stand-in REST server powered by Node, TypeScript, and OpenAPI.<
 
 </table>
 
-<h2 id="quick-start">Got 60 Seconds? Try it!</h2>
+<div align="center"  markdown="1">
+
+[![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpmcelhaney%2Fcounterfact%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/pmcelhaney/counterfact/main) ![MIT License](https://img.shields.io/badge/license-MIT-blue)
 
-Copy this into your terminal. The only prerequisite is Node 16+.
+
+</div>
+
+<h2 id="quick-start">Got 60 Seconds? Try me!</h2>
+
+Copy the following command into your terminal. The only prerequisite is Node 16+.
 
 ```sh copy
 npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api --open
@@ -66,8 +70,6 @@ You can use Swagger to try out the auto-generated API. Out of the box, it return
 
 📗 See [Usage](./docs/usage.md) for detailed documentation.
 
-<br>
-
-## Support
+---
 
-Counterfact is brand new as of October 3, 2022. Please send feedback / questions to pmcelhaney@gmail.com or [create a new issue](https://github.com/pmcelhaney/counterfact/issues/new). If you like what you see, please give this project a star!
+Counterfact is brand new as of October 5, 2022. Please send feedback / questions to pmcelhaney@gmail.com or [create a new issue](https://github.com/pmcelhaney/counterfact/issues/new). If you like what you see, please give this project a star!

package/_config.yaml

@@ -0,0 +1,12 @@
+remote_theme: pages-themes/dinky@v0.2.0
+plugins:
+- jekyll-remote-theme
+- jekyll-seo-tag
+markdown: GFM
+theme: jekyll-theme-cayman
+title: Counterfact
+description: OpenAPI to TypeScript generator and mock server
+url: https://counterfact.dev
+author: Partrick McElhaney
+google_analytics: G-2QHMETF62T
+

package/_includes/head-custom-google-analytics.html

@@ -0,0 +1,13 @@
+<script
+  async
+  src="https://www.googletagmanager.com/gtag/js?id={{ site.google_analytics }}"
+></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() {
+    dataLayer.push(arguments);
+  }
+  gtag("js", new Date());
+
+  gtag("config", "{{ site.google_analytics }}");
+</script>

package/bin/counterfact.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
 import nodePath from "node:path";
+import repl from "node:repl";
 
 import { program } from "commander";
 import open from "open";
 
 import { generate } from "../src/typescript-generator/generate.js";
-import { start } from "../src/start.js";
+import { start } from "../src/server/start.js";
 
 const DEFAULT_PORT = 3100;
 
@@ -23,7 +24,7 @@ async function main(source, destination) {
   const startServer = options.server || includeSwagger;
 
   if (startServer) {
-    await start({
+    const { contextRegistry } = await start({
       basePath,
       port: options.port,
       openApiPath: source,
@@ -33,6 +34,14 @@ async function main(source, destination) {
     process.stdout.write(
       `API is running at http://localhost:${options.port}.\n`
     );
+
+    process.stdout.write(
+      '\n\nStarting REPL... (start with `const context = loadContext("/")`)\n'
+    );
+
+    const replServer = repl.start("> ");
+
+    replServer.context.loadContext = (path) => contextRegistry.find(path);
   }
 
   if (openBrowser) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "a library for building a fake REST API for testing",
   "type": "module",
   "main": "./src/counterfact.js",
@@ -40,8 +40,8 @@
     "@stryker-mutator/jest-runner": "6.2.2",
     "@types/koa": "2.13.5",
     "@types/koa-static": "^4.0.2",
-    "eslint": "8.24.0",
-    "eslint-config-hardcore": "25.0.0",
+    "eslint": "8.25.0",
+    "eslint-config-hardcore": "25.1.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "^3.2.5",
     "eslint-plugin-etc": "^2.0.2",
@@ -53,7 +53,7 @@
     "jest": "28.1.2",
     "nodemon": "2.0.20",
     "stryker-cli": "1.0.2",
-    "supertest": "6.2.4"
+    "supertest": "6.3.0"
   },
   "dependencies": {
     "@hapi/accept": "^6.0.0",

package/src/client/index.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Counterfact</title>
+    <meta name="description" content="Counterfact dashboard" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style type="text/css">
+      body {
+        font-family: sans-serif;
+
+        margin: 20vh;
+        font-size: 3vh;
+        text-align: center;
+      }
+
+      ul {
+        list-style: none;
+        margin: 0;
+        line-height: 2em;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Counterfact is running!</h1>
+    <ul>
+      <li>
+        The generated code is at<br /><a href="vscode://file{{basePath}}"
+          >{{basePath}}</a
+        >
+      </li>
+      <li>
+        You can explore the API using
+        <a href="/counterfact/swagger">Swagger UI</a>
+      </li>
+      <li>
+        <a
+          href="https://github.com/pmcelhaney/counterfact/blob/main/docs/usage.md#generated-code-"
+          >How does this work?</a
+        >
+      </li>
+    </ul>
+  </body>
+</html>

package/src/{counterfact.js → server/counterfact.js}

@@ -6,7 +6,8 @@ import os from "node:os";
 import $RefParser from "json-schema-ref-parser";
 import yaml from "js-yaml";
 
-import { readFile } from "./read-file.js";
+import { readFile } from "../util/read-file.js";
+
 import { Registry } from "./registry.js";
 import { Dispatcher } from "./dispatcher.js";
 import { koaMiddleware } from "./koa-middleware.js";
@@ -39,7 +40,7 @@ export async function counterfact(
   )}/`;
 
   fs.copyFile(
-    nodePath.join(__dirname, "../templates/response-builder-factory.ts"),
+    nodePath.join(__dirname, "../../templates/response-builder-factory.ts"),
     nodePath.join(basePath, "response-builder-factory.ts")
   );
 
@@ -69,5 +70,10 @@ export async function counterfact(
 
   await moduleLoader.watch();
 
-  return { koaMiddleware: koaMiddleware(dispatcher), registry, moduleLoader };
+  return {
+    koaMiddleware: koaMiddleware(dispatcher),
+    registry,
+    moduleLoader,
+    contextRegistry,
+  };
 }

package/src/{start.js → server/start.js}

@@ -5,8 +5,12 @@ import bodyParser from "koa-bodyparser";
 import { koaSwagger } from "koa2-swagger-ui";
 import yaml from "js-yaml";
 
+import { readFile } from "../util/read-file.js";
+
 import { counterfact } from "./counterfact.js";
-import { readFile } from "./read-file.js";
+
+// eslint-disable-next-line no-underscore-dangle
+const __dirname = nodePath.dirname(new URL(import.meta.url).pathname);
 
 const DEFAULT_PORT = 3100;
 
@@ -43,46 +47,17 @@ function swaggerUi(app, openApiPath, port) {
   );
 }
 
-export function landingPageBody(basePath) {
-  return `
-  <html>
-    <head>
-      <title>Counterfact</title>
-      <style type="text/css">
-        body {
-          font-family: sans-serif;
-        
-          margin: 20vh;
-          font-size: 3vh;
-          text-align: center;
-        }
-
-        ul {
-          list-style: none;
-          margin: 0;
-          line-height: 2em;
-        }
-
-       
-      </style>
-    </head>
-    <body>
-      <h1>Counterfact is running!</h1>
-      <ul> 
-        
-        <li>The generated code is at<br><a href="vscode://file${basePath}">${basePath}</a></li>
-        <li>You can explore the API using <a href="/counterfact/swagger">Swagger UI</a></li>
-        <li><a href="https://github.com/pmcelhaney/counterfact/blob/main/docs/usage.md#generated-code-">How does this work?</a></li>
-      </ul>  
-    </body>
-  </html>
-`;
+export async function landingPageBody(basePath) {
+  const body = await readFile(nodePath.join(__dirname, "../client/index.html"));
+
+  return body.replaceAll("{{basePath}}", basePath);
 }
 
 export function landingPage(app, basePath) {
   app.use(async (ctx, next) => {
     if (ctx.URL.pathname === "/counterfact") {
-      ctx.body = landingPageBody(basePath);
+      // eslint-disable-next-line require-atomic-updates
+      ctx.body = await landingPageBody(basePath);
 
       return;
     }
@@ -108,9 +83,14 @@ export async function start({
 
   app.use(bodyParser());
 
-  const { koaMiddleware } = await counterfact(basePath, openApiPath);
+  const { koaMiddleware, contextRegistry } = await counterfact(
+    basePath,
+    openApiPath
+  );
 
   app.use(koaMiddleware);
 
   app.listen(port);
+
+  return { contextRegistry };
 }

package/src/typescript-generator/specification.js

@@ -2,7 +2,7 @@ import nodePath from "node:path";
 
 import yaml from "js-yaml";
 
-import { readFile } from "../read-file.js";
+import { readFile } from "../util/read-file.js";
 
 import { Requirement } from "./requirement.js";
 

package/test/{context-registry.test.js → server/context-registry.test.js}

@@ -1,4 +1,7 @@
-import { ContextRegistry, parentPath } from "../src/context-registry.js";
+import {
+  ContextRegistry,
+  parentPath,
+} from "../../src/server/context-registry.js";
 
 describe("moduleRegistry", () => {
   it("finds a context that exactly matches the path", () => {

package/test/{counterfact.test.js → server/counterfact.test.js}

@@ -1,9 +1,8 @@
 import supertest from "supertest";
 import Koa from "koa";
 
-import { counterfact } from "../src/counterfact.js";
-
-import { withTemporaryFiles } from "./lib/with-temporary-files.js";
+import { counterfact } from "../../src/server/counterfact.js";
+import { withTemporaryFiles } from "../lib/with-temporary-files.js";
 
 describe("integration test", () => {
   it("finds a path", async () => {

package/test/{dispatcher.test.js → server/dispatcher.test.js}

@@ -1,6 +1,6 @@
-import { Dispatcher } from "../src/dispatcher.js";
-import { ContextRegistry } from "../src/context-registry.js";
-import { Registry } from "../src/registry.js";
+import { Dispatcher } from "../../src/server/dispatcher.js";
+import { ContextRegistry } from "../../src/server/context-registry.js";
+import { Registry } from "../../src/server/registry.js";
 
 describe("a dispatcher", () => {
   it("dispatches a get request to a server and returns the response", async () => {

package/test/{koa-middleware.test.js → server/koa-middleware.test.js}

@@ -1,7 +1,7 @@
-import { Registry } from "../src/registry.js";
-import { Dispatcher } from "../src/dispatcher.js";
-import { koaMiddleware } from "../src/koa-middleware.js";
-import { ContextRegistry } from "../src/context-registry.js";
+import { Registry } from "../../src/server/registry.js";
+import { Dispatcher } from "../../src/server/dispatcher.js";
+import { koaMiddleware } from "../../src/server/koa-middleware.js";
+import { ContextRegistry } from "../../src/server/context-registry.js";
 
 describe("koa middleware", () => {
   it("passes the request to the dispatcher and returns the response", async () => {

package/test/{module-loader.test.js → server/module-loader.test.js}

@@ -1,10 +1,9 @@
 import { once } from "node:events";
 
-import { ModuleLoader } from "../src/module-loader.js";
-import { Registry } from "../src/registry.js";
-import { ContextRegistry } from "../src/context-registry.js";
-
-import { withTemporaryFiles } from "./lib/with-temporary-files.js";
+import { ModuleLoader } from "../../src/server/module-loader.js";
+import { Registry } from "../../src/server/registry.js";
+import { ContextRegistry } from "../../src/server/context-registry.js";
+import { withTemporaryFiles } from "../lib/with-temporary-files.js";
 
 describe("a module loader", () => {
   it("finds a file and adds it to the registry", async () => {

package/test/{registry.test.js → server/registry.test.js}

@@ -1,4 +1,4 @@
-import { Registry } from "../src/registry.js";
+import { Registry } from "../../src/server/registry.js";
 
 describe("a scripted server", () => {
   it("knows if a handler exists for a request method at a path", () => {

package/test/{response-builder.test.js → server/response-builder.test.js}

@@ -1,4 +1,4 @@
-import { createResponseBuilder } from "../src/response-builder.js";
+import { createResponseBuilder } from "../../src/server/response-builder.js";
 
 describe("a response builder", () => {
   it("starts building a response object when the status is selected", () => {

package/test/server/start.test.js

@@ -0,0 +1,10 @@
+import { landingPageBody } from "../../src/server/start.js";
+
+describe("start", () => {
+  it("renders the landing page", async () => {
+    const basePath = "/home/user/counterfact";
+    const result = await landingPageBody(basePath);
+
+    expect(result).toContain(basePath);
+  });
+});

package/test/{tools.test.js → server/tools.test.js}

@@ -1,4 +1,4 @@
-import { Tools } from "../src/tools.js";
+import { Tools } from "../../src/server/tools.js";
 
 describe("tools", () => {
   it("oneOf()", () => {

package/test/{transpiler.test.js → server/transpiler.test.js}

@@ -2,9 +2,8 @@ import { once } from "node:events";
 import fs from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 
-import { Transpiler } from "../src/transpiler.js";
-
-import { withTemporaryFiles } from "./lib/with-temporary-files.js";
+import { Transpiler } from "../../src/server/transpiler.js";
+import { withTemporaryFiles } from "../lib/with-temporary-files.js";
 
 const TYPESCRIPT_SOURCE = "const x:number = 1;\n";
 const JAVASCRIPT_SOURCE = "var x = 1;\n";

package/test/start.test.js

@@ -1,10 +0,0 @@
-import { landingPageBody } from "../src/start.js";
-
-describe("start", () => {
-  it("renders the landing page", () => {
-    const basePath = "/home/user/counterfact";
-    const result = landingPageBody(basePath);
-
-    expect(result).toContain(basePath);
-  });
-});