counterfact 0.10.3 → 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,17 @@
 # counterfact
 
+## 0.12.0
+
+### Minor Changes
+
+- 1a622d2: a REPL allows you to interact with the server's context programatically
+
+## 0.11.0
+
+### Minor Changes
+
+- 5a7e12b: --open opens the browser to a landing page with pointers to the code, Swagger, and the docs
+
 ## 0.10.3
 
 ### Patch 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,35 +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_
 
+[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.
 
-
-[Watch Demo](#watch-demo) | [Quick Start](#quick-start) |  [Documentation](#documentation) | [Support](#support)
-
-
-
-</div>
-
-
-
-<div align="center">
-Counterfact is a stand-in REST server powered by Node, TypeScript, and OpenAPI.<br>It simulates complex, stateful back end behavior without running the whole stack.
 </div>
 
 <br>
 
-<table align="center" cols="2">
+<table align="center" cols="2"  markdown="1">
 
 <tr>
 <td>
@@ -52,33 +38,23 @@ Counterfact is a stand-in REST server powered by Node, TypeScript, and OpenAPI.<
 
 </table>
 
+<div align="center"  markdown="1">
 
-<div id="watch-demo" align="center">
+[![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)
 
-```
 
-
-
-
-
-     video will go here
-
-
-
-
-```
 </div>
 
+<h2 id="quick-start">Got 60 Seconds? Try me!</h2>
 
-## Quick Start
-
-Try it now with one command. The only prequisite is Node 16+. 
+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
 ```
 
-### What does it do?
+<details>
+<summary>What does that command do?</summary>
 
 1. installs the `@latest` version of `counterfact`
 2. reads an [OpenAPI 3](https://oai.github.io/Documentation/) document (`https://petstore3.swagger.io/api/v3/openapi.json`)
@@ -86,14 +62,14 @@ npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api --op
 4. starts a server which implements the API
 5. opens your browser to [Swagger UI](https://swagger.io/tools/swagger-ui/) (`--open`)
 
-You can use Swagger to try out the auto-generated API. Out of the box, it returns random responses using metadata from the OpenAPI document. You can edit the files under `./api/paths` to add more realistic behavior. There's no need to restart the server.
-
+You can use Swagger to try out the auto-generated API. Out of the box, it returns random responses using metadata from the OpenAPI document. Edit the files under `./api/paths` to add more realistic behavior. There's no need to restart the server.
 
-## Documentation
+</details>
 
-Coming soon!
+<br>
 
+📗 See [Usage](./docs/usage.md) for detailed documentation.
 
-## 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,10 +34,18 @@ 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) {
-    await open(`http://localhost:${options.port}/counterfact/swagger`);
+    await open(`http://localhost:${options.port}/counterfact`);
   }
 }