start for docblock check

package.json

@@ -25,6 +25,7 @@
     "indexer": "turbo index",
     "license": "pnpm zx scripts/license.mjs",
     "lint": "turbo lint",
+    "postlint": "pnpm zx scripts/docblock.mjs",
     "lint:fs": "pnpm ls-lint",
     "test": "turbo test"
   },
@@ -34,6 +35,7 @@
     "@biomejs/biome": "^1.9.3",
     "@changesets/changelog-git": "^0.2.0",
     "@changesets/cli": "^2.27.9",
+    "comment-parser": "^1.4.1",
     "@ls-lint/ls-lint": "2.3.0-beta.1",
     "@swc/core": "^1.7.36",
     "rimraf": "^5.0.10",

scripts/docblock.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env zx
+
+/*
+ * Copyright 2024 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { parseFileSync } from '@swc/core';
+import { parse } from 'comment-parser';
+import { fs, glob } from 'zx';
+
+const SWC_OPTIONS = {
+  syntax: 'typescript',
+  target: 'es2022',
+};
+
+function exportsReducer(acc, node) {
+  if (node.type === 'ExportDeclaration') {
+    if (node.declaration.identifier) {
+      acc.push(node.declaration.identifier.value);
+    } else if (node.declaration.declarations) {
+      for (const inner of node.declaration.declarations) {
+        acc.push(inner.id.value);
+      }
+    }
+  }
+
+  return acc;
+}
+
+function getFileDetails(path) {
+  const ast = parseFileSync(path, SWC_OPTIONS);
+  const source = fs.readFileSync(path, 'utf8');
+
+  const exports = ast.body.reduce(exportsReducer, []);
+  const [pragma, ...list] = pragmaParser(source);
+
+  const result = [source];
+
+  switch (pragma) {
+    case 'ignore':
+      result.push(
+        list[0] === '*' ? [] : exports.filter((name) => !list.includes(name)),
+      );
+      break;
+    case 'only':
+      result.push(exports.filter((name) => list.includes(name)));
+      break;
+    default:
+      result.push(exports);
+      break;
+  }
+
+  return result;
+}
+
+const pragmaParser = (() => {
+  const rCleaner = /,\s*/;
+  const rPragma = /\/\/\s*@export-(ignore|only)(?:\s*\[([^\]]+)\])?/;
+  const rPrivate = /\/\/\s*__private-exports/i;
+
+  return (src) => {
+    if (src.match(rPrivate)?.[0]) {
+      return ['ignore', '*'];
+    }
+
+    const found = src.match(rPragma);
+
+    if (!found) {
+      return [];
+    }
+
+    const pragmas = found
+      .slice(1)
+      .reduce((a, b = '*') => [
+        a,
+        ...(b ? b.replace(rCleaner, ',').split(',') : b),
+      ]);
+
+    if (pragmas[0] === 'only' && pragmas[1] === '*') {
+      return [];
+    }
+
+    return pragmas;
+  };
+})();
+
+async function run() {
+  const noDocblock = (
+    await glob(['**/*.{js,ts,tsx,mjs}'], {
+      ignore: [
+        '**/.github/**',
+        '**/apps/**',
+        '**/__fixtures__/**',
+        '**/__mock__/**',
+        '**/coverage/**',
+        '**/dist/**',
+        '**/node_modules/**',
+        '**/tooling/**',
+        '**/*.test*',
+        '**/*.config*',
+        '**/*.css*',
+        '**/*.stories*',
+      ],
+    })
+  ).filter((file) => {
+    try {
+      const [source, exports] = getFileDetails(file);
+
+      // has exports and no docblock
+      return exports.length && !parse(source).length;
+    } catch (_) {
+      // ignore non-parsing files
+      return false;
+    }
+  });
+
+  if (noDocblock.length) {
+    console.error(
+      `${noDocblock.length} files missing a docblock:`,
+      JSON.stringify(noDocblock, null, 4),
+    );
+
+    // TODO: enable error-ing once all file are complying
+    // process.exit(1);
+  }
+}
+
+await run();