@appland/scanner 1.71.3 → 1.71.5

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@appland/scanner-v1.71.5](https://github.com/getappmap/appmap-js/compare/@appland/scanner-v1.71.4...@appland/scanner-v1.71.5) (2022-10-17)
+
+
+### Bug Fixes
+
+* Fix unresolved type in Rule.Options ([f4ed63c](https://github.com/getappmap/appmap-js/commit/f4ed63ca27e7c79b8e9bdb9faf63c9b3cd10145f))
+
+# [@appland/scanner-v1.71.4](https://github.com/getappmap/appmap-js/compare/@appland/scanner-v1.71.3...@appland/scanner-v1.71.4) (2022-10-13)
+
+
+### Bug Fixes
+
+* Export and package types for @appland/scanner ([f0b1583](https://github.com/getappmap/appmap-js/commit/f0b15838d463806322836259ed6866353e9454d8))
+
 # [@appland/scanner-v1.71.3](https://github.com/getappmap/appmap-js/compare/@appland/scanner-v1.71.2...@appland/scanner-v1.71.3) (2022-10-11)
 
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@appland/scanner",
-  "version": "1.71.3",
+  "version": "1.71.5",
   "description": "",
   "bin": "built/cli.js",
   "files": [
     "built",
-    "doc"
+    "doc",
+    "src/types.d.ts"
   ],
+  "types": "src/types.d.ts",
   "scripts": {
     "build": "mkdir -p built && cp -r src/sampleConfig built && tsc -p tsconfig.build.json && yarn schema && yarn doc",
     "build-native": "yarn build && ./bin/build-native",

package/src/types.d.ts

@@ -0,0 +1,154 @@
+import { AppMap, Event } from '@appland/models';
+import { SqliteParser } from '@appland/models/types/sqlite-parser';
+import { URL } from 'url';
+
+/**
+ * Each Rule in the scanner library wants to consider some set of events as it decides whether the code should be flagged or not.
+ * A Scope is a way of declaring how these "sets" are defined. A common scope is `http_server_request`. The rule will look at each HTTP
+ * server request separately; what happens in one request is irrelevant to the next. For example, when looking for authz_before_authn, each HTTP
+ * server request is considered separately.
+ *
+ * `http_server_request` is one example of a "command". Other types of commands are: CLI commands and background jobs. Each of these has a
+ * defined beginning and end, and is logically completely separate from any other command.
+ *
+ * Some rules are relevant only to HTTP server requests - such as `http500`. Others are applicable to any kind of command - such as `nPlusOneQuery`.
+ *
+ * Finally, other rules simply want to look for a certain condition regardless of where it occurs. For example, Too many SQL joins will flag any
+ * query anywhere in the AppMap, even if it's not part of a command. This rule uses the root scope, which yields a new scope for every root-level Event
+ * (root-level = "has no parent").
+ *
+ * Ideally, AppMaps would not contain any events that are not part of a command - because without knowing the command, we don't really have any context
+ * of what the code is trying to do. But, anticipating that this may sometimes happen, "root" scope is a good choice for a rule that may flag code
+ * anywhere in the AppMap.
+ */
+export type ScopeName =
+  | 'root'
+  | 'command'
+  | 'http_client_request'
+  | 'http_server_request'
+  | 'transaction';
+
+/**
+ * Indicates the aspect of software quality that is most relevant to a rule.
+ */
+export type ImpactDomain = 'Security' | 'Performance' | 'Maintainability' | 'Stability';
+
+/**
+ * Scope provides an Event at the root of the scope, and a Generator to iterate over its descendants.
+ */
+interface Scope {
+  scope: Event;
+  events: () => Generator<Event>;
+}
+
+/**
+ * Level indicates the priority of a finding.
+ */
+export type Level = 'warning' | 'error';
+
+type StringFilter = (value: string) => boolean;
+
+/**
+ * EventFilter is used by Rule to select Events that will be analyzed for findings.
+ * The event filter is always applied to the Scope.scope event. If enumerateScope is true,
+ * the filter is applied to all Scope.events as well.
+ */
+type EventFilter = (e: Event, appMapIndex: AppMapIndex) => boolean;
+
+/**
+ * MatchResult is created by a rule when it matches an Event.
+ */
+export interface MatchResult {
+  level?: Level;
+  event: Event;
+  message: string;
+  participatingEvents?: Record<string, Event>;
+  groupMessage?: string;
+  occurranceCount?: number;
+  relatedEvents?: Event[];
+}
+
+type MatcherResult =
+  | Promise<boolean | string | MatchResult[]>
+  | boolean
+  | string
+  | MatchResult[]
+  | undefined;
+
+type EventType = 'http_server_request' | 'http_client_request' | 'sql_query' | 'function';
+
+export type QueryAST = SqliteParser.ListStatement | null;
+
+interface AppMapIndex {
+  appMap: AppMap;
+
+  sqlAST(event: Event): QueryAST | undefined;
+
+  sqlNormalized(event: Event): string;
+}
+
+/**
+ * Matcher function is part of a rule. It's applied to an Event to determine whether there is a finding
+ * on this event. If the Matcher returns true, a string, or a MatchResult[], then finding(s) are created.
+ */
+type Matcher = (e: Event, appMapIndex: AppMapIndex, eventFilter: EventFilter) => MatcherResult;
+
+/**
+ * Finding is the full data structure that is created when a Rule matches an Event.
+ *
+ * The Rule only needs to return a boolean, string, or MatchResult. The scanner framework
+ * adds the rest of the information to build the complete finding.
+ */
+interface Finding {
+  appMapFile: string;
+  checkId: string;
+  ruleId: string;
+  ruleTitle: string;
+  event: Event;
+  hash: string; // Deprecated for local use. Still used to integrate local results with the server.
+  hash_v2: string;
+  scope: Event;
+  message: string;
+  stack: string[];
+  groupMessage?: string;
+  occurranceCount?: number;
+  relatedEvents?: Event[];
+  impactDomain?: ImpactDomain;
+  // Map of events by functional role name; for example, logEvent, secret, scope, etc.
+  participatingEvents?: Record<string, Event>;
+}
+
+interface RuleLogic {
+  // Tests an event in the scope see if it matches the rule conditions.
+  matcher: Matcher;
+  // When specified by the rule, only events which pass the where filter
+  // will be passed to the matcher.
+  where?: EventFilter;
+  // When specified by the rule, provides a detailed message for a finding on a specific event.
+  message?: (scope: Event, event: Event) => string;
+}
+
+interface Rule {
+  // Unique id of the rule.
+  id: string;
+  // Simple text description of the rule.
+  title: string;
+  // Longer text description of the rule.
+  description: string;
+  // URL to the documentation.
+  url?: string;
+  // labels which the rule depends on.
+  labels?: string[];
+  // Specifies which sub-tree events will be identified as "root events of concern".
+  // Events which are outside of any scope will not be processed by the rule.
+  scope?: ScopeName;
+  // Whether to pass all the events in the scope to the matcher. If false, only the scope event
+  // is passed to the matcher, and the rule should traverse the scope as needed.
+  enumerateScope: boolean;
+  impactDomain?: ImpactDomain;
+  references?: Record<string, URL>;
+  // User-defined options for the rule.
+  Options?: any; // FIXME
+  // Function to instantiate the rule logic from configured options.
+  build: (options: this['Options']) => RuleLogic;
+}