Merge pull request #5 from ProjectIgnis/fixes-and-improvements

Batch fixes and improvements

.github/workflows/deploy.yml

@@ -34,20 +34,20 @@ jobs:
         with:
           path: main
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: '20.x'
           cache: npm
           cache-dependency-path: ./main
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Build Site
         working-directory: main
         run: |-
           npm ci
           npm run book:build
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
+        uses: actions/upload-pages-artifact@v3
         with:
           path: main/docs/.vitepress/dist
 
@@ -62,4 +62,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

package.json

@@ -26,6 +26,7 @@
   "author": "that-hatter",
   "license": "AGPL-3.0-or-later",
   "devDependencies": {
+    "@types/node": "^22.5.5",
     "@typescript-eslint/eslint-plugin": "^5.26.0",
     "@typescript-eslint/parser": "^5.50.0",
     "@typescript-eslint/type-utils": "^5.50.0",
@@ -40,7 +41,7 @@
     "vue": "^3.3.4"
   },
   "dependencies": {
-    "@that-hatter/scrapi-factory": "^0.3.1",
-    "vitepress": "^1.0.0-rc.32"
+    "@that-hatter/scrapi-factory": "^0.3.2",
+    "vitepress": "^1.3.4"
   }
 }

src/apiPage/Constant.ts

@@ -110,6 +110,17 @@ const valueSection = ({ value }: sf.Constant, { bitmaskInt }: sf.Enum) => {
   return pipe(value, String, md.inlineCode, RNEA.of, md.paragraph);
 };
 
+const usageExamplesLink = (ct: sf.Constant) =>
+  O.some(
+    md.link(
+      'https://github.com/search?q=repo%3AProjectIgnis%2FCardScripts+' +
+        encodeURIComponent(ct.name) +
+        '&type=code',
+      O.none,
+      [md.text('Usage Examples')]
+    )
+  );
+
 const getNamespace = (ct: sf.Constant) => (api: sf.API) =>
   pipe(
     api.namespaces.record,
@@ -145,8 +156,8 @@ const quickLinksSection = (ct: sf.Constant) =>
     R.sequenceArray,
     R.map((links) =>
       pipe(
-        [BindingInfo.sourceLink(ct), ...links],
-        RA.filterMap(identity),
+        [BindingInfo.sourceLink(ct), usageExamplesLink(ct), ...links],
+        RA.compact,
         RA.intersperse<md.PhrasingContent>(md.text(' | ')),
         RNEA.fromReadonlyArray,
         O.map(md.superscript),

src/apiPage/Function.ts

@@ -1,14 +1,5 @@
 import type * as sf from '@that-hatter/scrapi-factory';
-import {
-  O,
-  R,
-  RA,
-  RNEA,
-  RR,
-  identity,
-  pipe,
-  string,
-} from '@that-hatter/scrapi-factory/fp';
+import { O, R, RA, RNEA, RR, pipe } from '@that-hatter/scrapi-factory/fp';
 import * as md from '@that-hatter/scrapi-factory/markdown';
 import * as BindingInfo from './shared/BindingInfo';
 import * as SignatureInfo from './shared/SignatureInfo';
@@ -20,16 +11,19 @@ type ParamSplit = Readonly<[sf.Parameter, ReadonlyArray<sf.Parameter>]>;
 const isColonCallable =
   (fn: sf.Function) =>
   ([{ type }]: ParamSplit): boolean =>
-    type.length === 1 && O.elem(string.Eq)(type[0], fn.namespace);
+    type.length === 1 &&
+    O.isSome(fn.namespace) &&
+    RNEA.head(type) === fn.namespace.value;
 
 const colonCallSample =
   (fn: sf.Function) =>
   ([fst, rest]: ParamSplit): string =>
     fst.name + ':' + fn.partialName + SignatureInfo.argsString(rest);
 
 // dot notation (or just using the name if there's no module)
-const dotCallSample = (fn: sf.Function) => (): string =>
-  fn.name + SignatureInfo.argsString(fn.parameters);
+const dotCallSample =
+  (fn: sf.Function, v: sf.Variant<sf.Function>) => (): string =>
+    fn.name + SignatureInfo.argsString(v.parameters);
 
 const sampleCodeFn =
   (fn: sf.Function) =>
@@ -38,10 +32,21 @@ const sampleCodeFn =
       RNEA.fromReadonlyArray(v.parameters),
       O.map(RNEA.unprepend),
       O.filter(isColonCallable(fn)),
-      O.match(dotCallSample(fn), colonCallSample(fn)),
+      O.match(dotCallSample(fn, v), colonCallSample(fn)),
       md.luaCode
     );
 
+const usageExamplesLink = (fn: sf.Function) =>
+  O.some(
+    md.link(
+      'https://github.com/search?q=repo%3AProjectIgnis%2FCardScripts+' +
+        encodeURIComponent(fn.partialName) +
+        '&type=code',
+      O.none,
+      [md.text('Usage Examples')]
+    )
+  );
+
 const getNamespace = (fn: sf.Function) => (api: sf.API) =>
   pipe(
     api.namespaces.record,
@@ -69,8 +74,8 @@ const quickLinksSection = (fn: sf.Function) =>
     namespaceLink(fn),
     R.map((ns) =>
       pipe(
-        [BindingInfo.sourceLink(fn), ns],
-        RA.filterMap(identity),
+        [BindingInfo.sourceLink(fn), usageExamplesLink(fn), ns],
+        RA.compact,
         RA.intersperse<md.PhrasingContent>(md.text(' | ')),
         RNEA.fromReadonlyArray,
         O.map(md.superscript),

src/apiPage/Type.ts

@@ -45,15 +45,15 @@ const fieldSection = (hdepth: md.HeadingDepth) => (field: sf.TableTypeField) =>
     Rd.map((heading) => md.listItem([heading, field.description]))
   );
 
-const mappedTypeSectionTitle = (mt: sf.TableTypeMappedType) => (api: sf.API) =>
-  pipe(
-    Comp.fullTypeMD(mt.valueType)(api),
-    RNEA.concat<md.PhrasingContent>([
-      md.text(' ['),
+const mappedTypeSectionTitle =
+  (mt: sf.TableTypeMappedType) =>
+  (api: sf.API): RNEA.ReadonlyNonEmptyArray<md.PhrasingContent> =>
+    [
+      md.text('[key: '),
       Comp.singleTypeMD(mt.keyType)(api),
-      md.text(']'),
-    ])
-  );
+      md.text('] '),
+      ...Comp.fullTypeMD(mt.valueType)(api),
+    ];
 
 const mappedTypeListItem =
   (hdepth: md.HeadingDepth) => (mt: sf.TableTypeMappedType) =>
@@ -107,7 +107,7 @@ const allMappedTypeKeys = memoize(({ name }: sf.TableType) => name)(
 
 const tableTypePageUniqueSection = (tt: sf.TableType) =>
   pipe(
-    tableTypeInfoSection(2)(tt),
+    tableTypeInfoSection(3)(tt),
     Rd.map((info) => md.combinedFragments([info, tt.guide]))
   );
 
@@ -222,7 +222,7 @@ export const page =
       usageList(
         tableTypes,
         allMappedTypeKeys,
-        'Table Types that use this type as index'
+        'Table Types that use this type as key'
       ),
       tp.supertype === sf.TABLE_TYPE_SYMBOL
         ? tableTypePageUniqueSection(tp)(api)

src/apiPage/shared/BindingInfo.ts

@@ -20,20 +20,17 @@ const statusMessages: Readonly<Record<string, string>> = {
     ' It may be modified or deleted without notice.' +
     ' Unstable versions will not be documented when modified or deleted.',
   deleted:
-    ' It is no longer available, and attempting to use it result in errors.',
+    ' It is no longer available, and attempting to use it will result in errors.',
   deprecated: '',
 };
 
-export const statusHatnote = ({
-  doctype,
-  status,
-}: sf.Topic & sf.BindingInfo): O.Option<md.Admonition> =>
+export const statusHatnote = ({ doctype, status }: sf.Topic & sf.BindingInfo) =>
   pipe(
     status.message,
     O.filter(() => status.index !== 'stable'),
     O.map((msg) =>
       md.paragraph([
-        md.text(`This ${doctype} is ${status.index}.`),
+        md.text(`This ${doctype} is ${status.index}. `),
         ...msg.children,
         md.text(statusMessages[status.index] ?? ''),
       ])

src/apiPage/shared/SignatureInfo.Parameter.ts

@@ -17,9 +17,7 @@ const partialSignature = (param: sf.Parameter) =>
   pipe(
     param.type,
     Comp.fullTypeMD,
-    R.map(
-      RNEA.concat<md.PhrasingContent>([md.text(' '), md.inlineCode(param.name)])
-    )
+    R.map(RNEA.concatW([md.text(' '), md.inlineCode(param.name)]))
   );
 const partialSignatureWithDefault = (param: sf.Parameter) =>
   pipe(

src/apiPage/shared/SignatureInfo.Return.ts

@@ -1,5 +1,12 @@
 import type * as sf from '@that-hatter/scrapi-factory';
-import { O, RA, RNEA, flow, pipe } from '@that-hatter/scrapi-factory/fp';
+import {
+  O,
+  RA,
+  RNEA,
+  flow,
+  identity,
+  pipe,
+} from '@that-hatter/scrapi-factory/fp';
 import * as md from '@that-hatter/scrapi-factory/markdown';
 import * as R from 'fp-ts/Reader';
 import * as Comp from './Component';
@@ -11,7 +18,9 @@ const partialSignature = (ret: sf.Return) =>
     ret.type,
     Comp.fullTypeMD,
     R.map(
-      RNEA.concatW(O.isSome(ret.name) ? [md.inlineCode(ret.name.value)] : [])
+      O.isSome(ret.name)
+        ? RNEA.concatW([md.text(' '), md.inlineCode(ret.name.value)])
+        : identity
     )
   );
 
@@ -20,8 +29,8 @@ export const combinedPartialSignatures = flow(
   R.sequenceArray,
   R.map(
     flow(
+      RA.intersperse<md.Children<md.Paragraph>>([md.text(', ')]),
       RA.flatten,
-      RA.intersperse<md.PhrasingContent>(md.text(', ')),
       RNEA.fromReadonlyArray,
       O.getOrElse((): md.Children<md.Paragraph> => [md.text('nil')])
     )

src/apiPage/shared/Topic.ts

@@ -1,7 +1,7 @@
 import type * as sf from '@that-hatter/scrapi-factory';
 import { O, RA, RNEA, RR, pipe } from '@that-hatter/scrapi-factory/fp';
 import * as md from '@that-hatter/scrapi-factory/markdown';
-import path from 'path';
+import path from 'node:path';
 import * as BindingInfo from './BindingInfo';
 
 // ----------------------------------------------------------------------------

src/book.ts

@@ -1,8 +1,8 @@
 import * as sf from '@that-hatter/scrapi-factory';
 import { R, RA, TE, flow, pipe } from '@that-hatter/scrapi-factory/fp';
 import * as md from '@that-hatter/scrapi-factory/markdown';
-import fs from 'fs';
-import path from 'path';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import * as Constant from './apiPage/Constant';
 import * as Enum from './apiPage/Enum';
 import * as Function from './apiPage/Function';
@@ -13,9 +13,9 @@ import * as Topic from './apiPage/shared/Topic';
 
 const writeFileTask = TE.tryCatchK(
   (filepath: string, content: string) =>
-    fs.promises
+    fs
       .mkdir(path.dirname(filepath), { recursive: true })
-      .then(() => fs.promises.writeFile(filepath, content)),
+      .then(() => fs.writeFile(filepath, content)),
   (err) => String(err instanceof Error ? err.message : err)
 );
 
@@ -97,12 +97,16 @@ const generateFiles = (api: sf.API) =>
   ]);
 
 const program = pipe(
-  sf.loadYard(sf.DEFAULT_OPTIONS),
+  {
+    ...sf.DEFAULT_OPTIONS,
+    directory: path.join(process.cwd(), '..', 'scrapiyard', 'api'),
+  },
+  sf.loadYard,
   TE.chainW(({ api }) => generateFiles(api)),
   TE.tapError((err) => {
     const errStr = JSON.stringify(err, null, 2);
     // eslint-disable-next-line functional/no-expression-statements
-    console.log(errStr);
+    console.error(errStr);
     return writeFileTask(path.join(process.cwd(), '..', 'error.json'), errStr);
   })
 );