Merge pull request #723 from OpenFn/fix-describe

describe-package: document anything with an @function tag
OpenFn · Jun 25, 2024 · d156311 · d156311
2 parents 5e54e44 + 6bfb359
commit d156311
Show file tree

Hide file tree

Showing 23 changed files with 179 additions and 27 deletions.
diff --git a/examples/dts-inspector/CHANGELOG.md b/examples/dts-inspector/CHANGELOG.md
@@ -1,5 +1,12 @@
 # dts-inspector
 
+## 1.0.17
+
+### Patch Changes
+
+- Updated dependencies [fa65a0f]
+  - @openfn/describe-package@0.0.20
+
 ## 1.0.16
 
 ### Patch Changes

diff --git a/examples/dts-inspector/package.json b/examples/dts-inspector/package.json
@@ -1,6 +1,6 @@
 {
   "name": "dts-inspector",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "",
   "main": "index.js",
   "type": "module",

diff --git a/integration-tests/worker/CHANGELOG.md b/integration-tests/worker/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @openfn/integration-tests-worker
 
+## 1.0.48
+
+### Patch Changes
+
+- @openfn/engine-multi@1.1.11
+- @openfn/lightning-mock@2.0.11
+- @openfn/ws-worker@1.2.1
+
 ## 1.0.47
 
 ### Patch Changes

diff --git a/integration-tests/worker/package.json b/integration-tests/worker/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@openfn/integration-tests-worker",
   "private": true,
-  "version": "1.0.47",
+  "version": "1.0.48",
   "description": "Lightning WOrker integration tests",
   "author": "Open Function Group <[email protected]>",
   "license": "ISC",

diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @openfn/cli
 
+## 1.4.1
+
+### Patch Changes
+
+- Updated dependencies [fa65a0f]
+  - @openfn/describe-package@0.0.20
+  - @openfn/compiler@0.1.3
+
 ## 1.4.0
 
 ### Minor Changes

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/cli",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "CLI devtools for the openfn toolchain.",
   "engines": {
     "node": ">=18",

diff --git a/packages/compiler/CHANGELOG.md b/packages/compiler/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @openfn/compiler
 
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [fa65a0f]
+  - @openfn/describe-package@0.0.20
+
 ## 0.1.2
 
 ### Patch Changes

diff --git a/packages/compiler/package.json b/packages/compiler/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/compiler",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Compiler and language tooling for openfn jobs.",
   "author": "Open Function Group <[email protected]>",
   "license": "ISC",

diff --git a/packages/describe-package/CHANGELOG.md b/packages/describe-package/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @openfn/describe-package
 
+## 0.0.20
+
+### Patch Changes
+
+- fa65a0f: Describe anything with an @function tag, consistent with docsite
+
 ## 0.0.19
 
 ### Patch Changes

diff --git a/packages/describe-package/package.json b/packages/describe-package/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/describe-package",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Utilities to inspect an npm package.",
   "author": "Open Function Group <[email protected]>",
   "license": "ISC",
@@ -32,7 +32,8 @@
     "build:worker": "tsm esbuild-worker.ts",
     "build:node": "tsup --config tsup.config.js src/index.ts",
     "build": "pnpm clean && pnpm build:node && pnpm build:worker",
-    "pack": "pnpm pack --pack-destination ../../dist"
+    "pack": "pnpm pack --pack-destination ../../dist",
+    "cli": "npx tsx src/cli.ts"
   },
   "keywords": [],
   "devDependencies": {
@@ -44,7 +45,7 @@
     "esbuild": "^0.18.14",
     "rimraf": "^3.0.2",
     "threads": "1.7.0",
-    "ts-node": "^10.9.1",
+    "ts-node": "^10.9.2",
     "tslib": "^2.4.0",
     "tsm": "^2.2.1",
     "tsup": "^7.2.0"

diff --git a/packages/describe-package/src/api.ts b/packages/describe-package/src/api.ts
@@ -64,7 +64,7 @@ export type ParameterDescription = {
  */
 export const describePackage = async (
   specifier: string,
-  _options: Options
+  _options: Options = {}
 ): Promise<PackageDescription> => {
   const { name, version } = getNameAndVersion(specifier);
   const project = new Project();

diff --git a/packages/describe-package/src/cli.ts b/packages/describe-package/src/cli.ts
@@ -0,0 +1,12 @@
+import { describePackage } from './api';
+
+const a = process.argv[2];
+
+async function run(specifier: string) {
+  const result = await describePackage(specifier, {});
+
+  console.log(result);
+}
+
+console.log('GENERATING FOR', a);
+run(a);
diff --git a/packages/describe-package/src/describe-project.ts b/packages/describe-package/src/describe-project.ts
@@ -97,7 +97,7 @@ const describeProject = (
         return true;
       }
       // Return all export aliases and public symbols
-      return symbol.isExportAlias || symbol.isPublic;
+      return symbol.isExportAlias || symbol.hasFunctionTag;
     })
     .reduce((symbols, symbol) => {
       if (symbol.isFunctionDeclaration) {

diff --git a/packages/describe-package/src/typescript/wrapped-symbol.ts b/packages/describe-package/src/typescript/wrapped-symbol.ts
@@ -86,10 +86,11 @@ export class WrappedSymbol {
     return this.symbol.valueDeclaration?.type;
   }
 
-  // A function is private unless it has a public tag
-  public get isPublic(): boolean {
-    return this.jsDocTags.some(
-      (tag: ts.JSDocTag) => tag.tagName.escapedText === 'public'
+  public get hasFunctionTag(): boolean {
+    return Boolean(
+      this.jsDocTags.find(
+        (tag: ts.JSDocTag) => tag.tagName.escapedText === 'function'
+      )
     );
   }
 

diff --git a/packages/describe-package/test/describe-project.test.ts b/packages/describe-package/test/describe-project.test.ts
@@ -74,7 +74,7 @@ test('Parse an empty file', async (t) => {
 
 test('Recognise a namespace', async (t) => {
   const ns = get('flavours');
-  t.is(ns.type, 'namespace')
+  t.is(ns.type, 'namespace');
 
   // Note that we don't do a lot with the namespace right now - we just acknowledge that its there
-});
+});
diff --git a/packages/describe-package/test/fixtures/stroopwafel.d.ts b/packages/describe-package/test/fixtures/stroopwafel.d.ts
@@ -1,14 +1,14 @@
 /**
  * Returns a traditional stroopwafel
- * @public
+ * @function
  * @example
  * traditional()
  */
 export declare function traditional(): string;
 
 /**
  * Returns a flavoured stroopwafel
- * @public
+ * @function
  * @param {string} flavour
  * @magic flavour - $.children[*]
  * @example
@@ -18,7 +18,7 @@ export declare function oneFlavour(flavour: string): string;
 
 /**
  * Returns a many flavoured stroopwafel
- * @public
+ * @function
  * @example
  * manyFlavours(['strawberry', 'cream'])
  * @example

diff --git a/packages/engine-multi/CHANGELOG.md b/packages/engine-multi/CHANGELOG.md
@@ -1,5 +1,11 @@
 # engine-multi
 
+## 1.1.11
+
+### Patch Changes
+
+- @openfn/compiler@0.1.3
+
 ## 1.1.10
 
 ### Patch Changes

diff --git a/packages/engine-multi/package.json b/packages/engine-multi/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/engine-multi",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Multi-process runtime engine",
   "main": "dist/index.js",
   "type": "module",

diff --git a/packages/lightning-mock/CHANGELOG.md b/packages/lightning-mock/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @openfn/lightning-mock
 
+## 2.0.11
+
+### Patch Changes
+
+- @openfn/engine-multi@1.1.11
+
 ## 2.0.10
 
 ### Patch Changes

diff --git a/packages/lightning-mock/package.json b/packages/lightning-mock/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/lightning-mock",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "private": true,
   "description": "A mock Lightning server",
   "main": "dist/index.js",

diff --git a/packages/ws-worker/CHANGELOG.md b/packages/ws-worker/CHANGELOG.md
@@ -1,5 +1,11 @@
 # ws-worker
 
+## 1.2.1
+
+### Patch Changes
+
+- @openfn/engine-multi@1.1.11
+
 ## 1.2.0
 
 ### Minor Changes

diff --git a/packages/ws-worker/package.json b/packages/ws-worker/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/ws-worker",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A Websocket Worker to connect Lightning to a Runtime Engine",
   "main": "dist/index.js",
   "type": "module",