fix: last fixes before first release (#16)

* fix: added final touches * refactor: types * fix: don't warn about missing inheritdoc in interfaces * fix: remove empty warnings from * fix: do not require inheritdoc for constructor --------- Co-authored-by: Gas One Cent <[email protected]>
defi-wonderland · Jan 15, 2024 · 44f8e46 · 44f8e46
1 parent 8904313
commit 44f8e46
Show file tree

Hide file tree

Showing 14 changed files with 71 additions and 78 deletions.
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ Want to quickly check if your natspec smells?
 Just run:
 
 ```
-npx @defi-wonderland/natspec-smells --include src --exclude test --exclude scripts
+npx @defi-wonderland/natspec-smells --include solidity --exclude solidity/(test|scripts)/**/*.sol
 ```
 
 ## Recommended setup
@@ -35,13 +35,13 @@ npx @defi-wonderland/natspec-smells --include src --exclude test --exclude scrip
 
    ```javascript
    /**
-    * For full explanation of each supported config, make sure to check the Config type below
+    * List of supported options: https://github.com/defi-wonderland/natspec-smells?tab=readme-ov-file#options
     */
 
    /** @type {import('@defi-wonderland/natspec-smells').Config} */
    module.exports = {
-     include: "src",
-     exclude: ["tests", "scripts"],
+     include: "solidity",
+     exclude: ["solidity/(test|scripts)/**/*.sol"],
    };
    ```
 
@@ -71,3 +71,4 @@ Natspec Smells was built with ❤️ by [Wonderland](https://defi.sucks).
 Wonderland the largest core development group in web3. Our commitment is to a financial future that's open, decentralized, and accessible to all.
 
 [DeFi sucks](https://defi.sucks), but Wonderland is here to make it better.
+``
diff --git a/example-natspec-smells.config.js b/example-natspec-smells.config.js
diff --git a/src/index.d.ts b/src/index.d.ts
diff --git a/src/main.ts b/src/main.ts
@@ -4,7 +4,7 @@ import { hideBin } from 'yargs/helpers';
 import { globSync } from 'fast-glob';
 import { getProjectCompiledSources } from './utils';
 import { Processor } from './processor';
-import { Config } from './types/config';
+import { Config } from './types';
 import { Validator } from './validator';
 
 (async () => {

diff --git a/src/processor.ts b/src/processor.ts
@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 import { Validator } from './validator';
 import { SourceUnit, FunctionDefinition, ContractDefinition } from 'solc-typed-ast';
-import { NodeToProcess } from './types/solc-typed-ast.d';
+import { NodeToProcess } from './types';
 import { getLineNumberFromSrc, parseNodeNatspec } from './utils';
 
 interface IWarning {
@@ -27,7 +27,7 @@ export class Processor {
         for (const node of nodes) {
           // Find warning messages of the natspec of the node
           const messages = this.validateNatspec(node);
-          if (messages) {
+          if (messages.length) {
             // Add the warning messages to the list together with the natspec location
             warnings.push({
               location: this.formatLocation(sourceUnit.absolutePath, fileContent, contract, node),

diff --git a/src/types.ts b/src/types.ts
@@ -0,0 +1,51 @@
+import {
+  EnumDefinition,
+  ErrorDefinition,
+  EventDefinition,
+  FunctionDefinition,
+  ModifierDefinition,
+  StructDefinition,
+  VariableDeclaration,
+} from 'solc-typed-ast';
+
+export interface Config {
+  include: string; // Required: Glob pattern of files to process.
+  exclude: string[]; // Optional: Glob patterns of files to exclude.
+  root: string; // Optional: Project root directory.
+  enforceInheritdoc: boolean; // Optional: True if all external and public functions should have @inheritdoc.
+  constructorNatspec: boolean; // Optional: True if the constructor should have natspec.
+}
+
+export interface NatspecDefinition {
+  name?: string;
+  content: string;
+}
+
+export interface Natspec {
+  inheritdoc?: NatspecDefinition;
+  tags: NatspecDefinition[];
+  params: NatspecDefinition[];
+  returns: NatspecDefinition[];
+}
+
+export interface ASTNodeRawDocumentation {
+  id: number;
+  nodeType: string;
+  src: string;
+  text: string;
+}
+
+export interface ASTNodeRaw {
+  name: string;
+  kind: string;
+  documentation?: ASTNodeRawDocumentation;
+}
+
+export type NodeToProcess =
+  | FunctionDefinition
+  | EnumDefinition
+  | ErrorDefinition
+  | EventDefinition
+  | ModifierDefinition
+  | VariableDeclaration
+  | StructDefinition;
diff --git a/src/types/config.d.ts b/src/types/config.d.ts
diff --git a/src/types/natspec.d.ts b/src/types/natspec.d.ts
diff --git a/src/types/solc-typed-ast.d.ts b/src/types/solc-typed-ast.d.ts
diff --git a/src/utils.ts b/src/utils.ts
@@ -1,8 +1,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { ASTKind, ASTReader, SourceUnit, compileSol } from 'solc-typed-ast';
-import { Natspec, NatspecDefinition } from './types/natspec.d';
-import { NodeToProcess } from './types/solc-typed-ast.d';
+import { Natspec, NatspecDefinition, NodeToProcess } from './types';
 
 export async function getSolidityFiles(dir: string): Promise<string[]> {
   let files = await fs.readdir(dir, { withFileTypes: true });

diff --git a/src/validator.ts b/src/validator.ts
@@ -1,6 +1,4 @@
-import { Config } from './types/config';
-import { Natspec } from './types/natspec';
-import { NodeToProcess } from './types/solc-typed-ast';
+import { Config, Natspec, NodeToProcess } from './types';
 import {
   EnumDefinition,
   ErrorDefinition,
@@ -9,6 +7,7 @@ import {
   ModifierDefinition,
   StructDefinition,
   VariableDeclaration,
+  ContractDefinition,
 } from 'solc-typed-ast';
 
 export class Validator {
@@ -97,14 +96,18 @@ export class Validator {
     let _requiresInheritdoc: boolean = false;
 
     // External or public function
-    _requiresInheritdoc ||= node instanceof FunctionDefinition && (node.visibility === 'external' || node.visibility === 'public');
+    _requiresInheritdoc ||=
+      node instanceof FunctionDefinition && (node.visibility === 'external' || node.visibility === 'public') && !node.isConstructor;
 
     // Internal virtual function
     _requiresInheritdoc ||= node instanceof FunctionDefinition && node.visibility === 'internal' && node.virtual;
 
     // Public variable
     _requiresInheritdoc ||= node instanceof VariableDeclaration && node.visibility === 'public';
 
+    // The node is in a contract
+    _requiresInheritdoc &&= node.parent instanceof ContractDefinition && node.parent.kind === 'contract';
+
     return _requiresInheritdoc;
   }
 }
diff --git a/test/mocks.ts b/test/mocks.ts
@@ -1,6 +1,5 @@
-import { Natspec } from '../src/types/natspec.d';
 import { SourceUnit, ContractDefinition, FunctionDefinition } from 'solc-typed-ast';
-import { NodeToProcess } from '../src/types/solc-typed-ast.d';
+import { Natspec, NodeToProcess } from '../src/types';
 
 export function mockNatspec(mockNatspec: Partial<Natspec>): Natspec {
   const natspec: Natspec = {

diff --git a/test/processor.test.ts b/test/processor.test.ts
@@ -1,5 +1,5 @@
-import { Config } from '../src/types/config';
 import { ContractDefinition, FunctionDefinition, UserDefinedType, UsingForDirective } from 'solc-typed-ast';
+import { Config } from '../src/types';
 import { getFileCompiledSource } from './utils';
 import { Processor } from '../src/processor';
 import { Validator } from '../src/validator';

diff --git a/test/validator.test.ts b/test/validator.test.ts
@@ -1,8 +1,7 @@
+import { ContractDefinition } from 'solc-typed-ast';
 import { Validator } from '../src/validator';
 import { getFileCompiledSource } from './utils';
-import { NodeToProcess } from '../src/types/solc-typed-ast.d';
-import { ContractDefinition } from 'solc-typed-ast';
-import { Config } from '../src/types/config';
+import { Config, NodeToProcess } from '../src/types';
 
 describe('Validator', () => {
   let contract: ContractDefinition;