@appport/assessment 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog: @appport/assessment
+
+## 0.1.0
+
+First release. Static assessment of an existing repository: evidence-backed capability candidates, readiness and a recommended exposure candidate. It reads; it executes, builds and writes nothing in the target.
+
+- Scanner 1 (the default): Go and Protocol Buffers; writes `appport.application-assessment/1`.
+- Scanner 2 (`assessRepository(path, { scanner: 2 })`, `appworks assess --scanner 2`): also reads HTTP routes registered in JavaScript and TypeScript (Express, Fastify, Koa router, Hono, NestJS) and writes `appport.application-assessment/2`. A route is evidence that an entry point exists and nothing more: it is never recommended and is not yet extractable (`spec/assessment-1.md` §11).
+- Scanner 1's output does not depend on scanner 2: assessments made with it reproduce.
+- Depends only on `@appport/protocol` 1.3.0.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @appport/assessment
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AppWorks existing-application assessment. It reads a repository statically and writes an `appport.application-assessment/1` artifact.
+The artifact is an evidence-backed inventory of the business capabilities the application exposes, how they are implemented, what they
+read, write and call, how they are authorized, validated and tested, and which one is the most reasonable first candidate for AppPort
+exposure. Specification: `spec/assessment-1.md` in [rkendel1/appworks](https://github.com/rkendel1/appworks). JSON Schema ships in `schemas/`.
+
+The `appworks` command comes with `@appport/extraction`. This package alone installs `appworks-assess`, which takes the same `assess`
+and `verify` commands.
+
+```sh
+appworks assess ./memos --output memos-assessment.json     # exit 0 (complete or partial), 1 fatal, 2 usage, 3 --strict and partial
+appworks verify memos-assessment.json --repo ./memos       # integrity, honesty, and every observed location against the files
+```
+
+```ts
+import { assessRepository, verifyAssessment } from "@appport/assessment";
+
+const assessment = assessRepository("./memos");
+assessment.recommendation;            // { candidate, reasons, ranking, beforeExposure } or null
+verifyAssessment(assessment, { repository: "./memos" });
+```
+
+| Export | Purpose |
+|---|---|
+| `assessRepository` | the assessment; options for limits, thresholds and (for tests) volatile metadata |
+| `verifyAssessment` | structure, evidence classes and references, verified/authority claims, digest; locations with `repository` |
+| `assessmentDigest`, `evidenceId` | the content rules (`digestOf` of `@appport/protocol`) |
+| `proposeCapabilityName`, `messageSchema` | the AppPort proposal rules |
+| types and constants | `ApplicationAssessment`, `Evidence`, `Candidate`, `ProposedCapability`, `ASSESSMENT_FORMAT`, `EVIDENCE_CLASSES`, `READINESS_CLASSES`, … |
+
+**Supported:** Protocol Buffers services with `google.api.http`, and Go (handlers, call graph, SQL literals, status codes, goroutines,
+outbound `net/http`, configuration keys, tests). `go.mod` and `package.json` are read as manifests. Other languages are counted and
+reported, and make an assessment partial.
+
+**Scanner 2** (`assessRepository(path, { scanner: 2 })`, `appworks assess --scanner 2`, format `appport.application-assessment/2`) also reads the HTTP
+routes a JavaScript or TypeScript application registers (Express, Fastify, Koa router, Hono, NestJS), with the prefixes of the mounts that lead to
+each, the middleware in front of it and, where one exists, its handler's definition. A route is evidence that an entry point exists and nothing
+more: no handler body is read and no shape is assumed, so a route is `investigate` at best, is never recommended, and cannot yet be extracted.
+Scanner 1 is the default and its output is unchanged, so existing digests still reproduce. See `spec/assessment-1.md` §11.
+
+**Guarantees:** it never writes to, executes, builds or imports anything in the target; it never follows symbolic links; it uses no network
+and no language model. Every observed fact has a location you can check; every inference names its basis; what it cannot determine is
+recorded as unknown. It never claims verified behavior, grants no authority, registers nothing, and its proposed capability is not a
+contract. Depends only on `@appport/protocol` 1.3.0. Part of the AppPort ecosystem, not of the AppPort protocol. Not implemented:
+extraction, compilation, execution and migration.

package/dist/analyze.d.ts

@@ -0,0 +1,40 @@
+import { type ApplicationAssessment } from "./artifact.js";
+export interface AssessOptions {
+    /**
+     * `1` (default): Go and Protocol Buffers, as before, writing `appport.application-assessment/1`.
+     * `2`: also reads HTTP routes from JavaScript and TypeScript (`http.ts`), writing `/2`. A different scanner can assess the same tree
+     * differently (`docs/compatibility.md`), so it is chosen, never switched on silently.
+     */
+    scanner?: 1 | 2;
+    maxFileBytes?: number;
+    excludedDirectories?: readonly string[];
+    maxCallDepth?: number;
+    maxReachableFunctions?: number;
+    smallSurface?: {
+        maxHandlerLines: number;
+        maxReachableFunctions: number;
+    };
+    /** Volatile metadata sources, for tests. They do not affect the digest. */
+    now?: () => Date;
+    id?: () => string;
+}
+export declare const DEFAULTS: {
+    readonly maxCallDepth: 12;
+    readonly maxReachableFunctions: 400;
+    readonly smallSurface: {
+        readonly maxHandlerLines: 80;
+        readonly maxReachableFunctions: 60;
+    };
+};
+/** Scanner 2's limitations: scanner 1's, with the languages entry replaced and the HTTP reader's added. */
+export declare function limitationsFor(scanner: 1 | 2): ReadonlyArray<{
+    code: string;
+    description: string;
+}>;
+export declare const LIMITATIONS: ReadonlyArray<{
+    code: string;
+    description: string;
+}>;
+/** Assesses the repository at `path`. Throws `RepositoryError` for a path that is not a readable directory. */
+export declare function assessRepository(path: string, options?: AssessOptions): ApplicationAssessment;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAOA,OAAO,EAUL,KAAK,qBAAqB,EAa3B,MAAM,eAAe,CAAC;AAQvB,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,YAAY,CAAC,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,qBAAqB,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,QAAQ;aACnB,YAAY,EAAE,EAAE;aAChB,qBAAqB,EAAE,GAAG;aAC1B,YAAY;iBAAI,eAAe,EAAE,EAAE;iBAAE,qBAAqB,EAAE,EAAE;;CACtD,CAAC;AAiBX,2GAA2G;AAC3G,wBAAgB,cAAc,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAQnG;AAED,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAU5E,CAAC;AAuCF,+GAA+G;AAC/G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,qBAAqB,CAwxBjG"}