@cplieger/deadset-ts 8.0.0-dev.7 → 8.0.0-dev.8

package/dist/src/scope.js

@@ -1,19 +1,22 @@
-import { ConfigError } from "./config.js";
+import { SCOPE_SCHEMA } from "./contract/config.generated.js";
+import { dotted, locatedFault, placeIn, readStrict, StrictJSONError } from "./json-document.js";
 import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.js";
-import { checkDocument } from "./schema.js";
-import { isRecord } from "./json-document.js";
 import { message } from "./product.js";
-/** The roles a scope document declares for a module. */
-const ROLE_TARGET = "target";
-const ROLE_CONSUMER = "consumer";
+import { firstRefusal } from "./schema.js";
+import { UsageError } from "./usage.js";
 /**
  * A scope document above this length is refused rather than decoded. It names one
  * target and its consumers, so a larger file is not one.
  */
 const MAX_DOCUMENT_LENGTH = 1 << 20;
 /**
- * A scope document that cannot be read as one. It ends the run with the failure
- * code: the run could not learn what to analyze, so it produced no answer.
+ * The bytes read of a scope document. A UTF-16 unit decodes from at most three bytes,
+ * so a document past the bound is past it within these.
+ */
+const MAX_DOCUMENT_BYTES = 3 * (MAX_DOCUMENT_LENGTH + 1);
+/**
+ * A scope that cannot be read as one. It ends the run with the failure code: the run
+ * could not learn what to analyze, so it produced no answer.
  */
 export class ScopeError extends Error {
     constructor(message) {
@@ -21,119 +24,48 @@ export class ScopeError extends Error {
         this.name = "ScopeError";
     }
 }
-const MODULE = {
-    kind: "section",
-    members: { id: { kind: "leaf" }, role: { kind: "leaf" }, path: { kind: "leaf" } },
-};
-/** The closed key list of the scope document, compared as bytes. */
-const SCOPE_ROOT = {
-    kind: "section",
-    members: {
-        target: MODULE,
-        workspace: { kind: "leaf" },
-        consumers: { kind: "list", members: MODULE.members ?? {} },
-    },
-};
-/**
- * One string member, or undefined where the document omits it. A member the
- * document writes is a string holding at least one character, so `null` and `""`
- * are refused rather than read as absent.
- */
-function stringMember(parent, name, at) {
-    if (!Object.hasOwn(parent, name)) {
-        return undefined;
-    }
-    const value = parent[name];
-    if (typeof value !== "string") {
-        throw new ScopeError(`scope: ${at === "" ? name : `${at}.${name}`} is not a string`);
-    }
-    if (value === "") {
-        throw new ScopeError(`scope: ${at === "" ? name : `${at}.${name}`} names nothing`);
-    }
-    return value;
-}
-function readModule(value, at, role, documentDir) {
-    if (!isRecord(value)) {
-        throw new ScopeError(`scope: ${at} is not an object`);
-    }
-    const declared = stringMember(value, "role", at);
-    if (declared !== undefined && declared !== role) {
-        throw new ScopeError(`scope: ${at}.role is ${JSON.stringify(declared)}, want ${JSON.stringify(role)}`);
-    }
-    const path = stringMember(value, "path", at);
-    if (path === undefined) {
-        throw new ScopeError(`scope: ${at}.path names nothing`);
-    }
-    return {
-        id: stringMember(value, "id", at) ?? "",
-        path: isAbsolutePath(path) ? path : joinPath(documentDir, path),
-    };
-}
-/**
- * Walks the document's text against the closed key list, refusing a key the list
- * does not declare, compared as bytes, and a key one object writes twice, which a
- * parse cannot report because it keeps the last value.
- */
-function checkKeys(text, file) {
-    try {
-        checkDocument(text, SCOPE_ROOT, `scope: ${file}`);
-    }
-    catch (error) {
-        if (error instanceof ConfigError) {
-            // The configuration's refusal names the nearest configuration key, which a
-            // scope document does not have.
-            throw new ScopeError(error.kind === "unimplemented-key"
-                ? `scope: ${file}: ${error.key} is not a declared key`
-                : error.message);
-        }
-        throw error;
-    }
+function refusal(file, place, reason) {
+    return new ScopeError(`scope: ${file}: ${place === "" ? "" : `${place}: `}${reason}`);
 }
 /**
- * Decodes the scope document at `file`. Decoding is strict: an undeclared key, a
- * key written twice in one object, and a value of a type the document does not
- * admit, `null` included, are errors, and a relative path inside the document
- * resolves against the document's own directory.
- *
- * The `workspace` key the format declares is checked and carries nothing here: it
- * names the file a Go consumer resolves the target through, and a TypeScript
- * project resolves one through its own compiler configuration.
+ * Decodes the scope document at `file`, held to the Contract's scope schema, a relative
+ * path resolved against the document's own directory. A document that cannot be read is
+ * a usage error, one that is refused a scope error. `workspace` is read by Go consumers
+ * alone: a TypeScript project resolves the target through its own compiler configuration.
  */
 export function readScope(host, file) {
     const absolute = resolvePath(host.workingDirectory(), file);
     let text;
     try {
-        text = host.readFile(absolute);
+        text = host.readFile(absolute, MAX_DOCUMENT_BYTES);
     }
     catch (error) {
-        throw new ScopeError(`scope: ${file}: ${message(error)}`);
+        throw new UsageError(`scope: ${file}: ${message(error)}`);
     }
     if (text.length > MAX_DOCUMENT_LENGTH) {
         throw new ScopeError(`scope: ${file} is longer than ${String(MAX_DOCUMENT_LENGTH)} characters`);
     }
     let value;
     try {
-        value = JSON.parse(text);
+        value = readStrict(text).value;
     }
     catch (error) {
-        throw new ScopeError(`scope: ${file}: ${message(error)}`);
+        if (!(error instanceof StrictJSONError)) {
+            throw error;
+        }
+        throw refusal(file, dotted(error.place), locatedFault(text, error));
     }
-    if (!isRecord(value)) {
-        throw new ScopeError(`scope: ${file} is not one JSON object`);
+    const refused = firstRefusal(SCOPE_SCHEMA, value);
+    if (refused !== undefined) {
+        throw refusal(file, dotted(placeIn(value, refused.pointer, refused.member)), refused.reason);
     }
-    checkKeys(text, file);
-    stringMember(value, "workspace", "");
+    const declared = value;
     const documentDir = dirnamePath(absolute);
-    if (!Object.hasOwn(value, "target")) {
-        throw new ScopeError(`scope: ${file} names no target`);
-    }
-    const target = readModule(value["target"], "target", ROLE_TARGET, documentDir);
-    const listed = Object.hasOwn(value, "consumers") ? value["consumers"] : [];
-    if (!Array.isArray(listed)) {
-        throw new ScopeError(`scope: ${file}: consumers is not an array`);
-    }
-    const consumers = listed.map((entry, index) => readModule(entry, `consumers[${String(index)}]`, ROLE_CONSUMER, documentDir));
-    return { target, consumers };
+    const moduleOf = (module) => ({
+        id: module.id ?? "",
+        path: isAbsolutePath(module.path) ? module.path : joinPath(documentDir, module.path),
+    });
+    return { target: moduleOf(declared.target), consumers: (declared.consumers ?? []).map(moduleOf) };
 }
 /** The single-package scope one directory is, when no scope document is given. */
 export function scopeForDir(host, dir) {

package/dist/src/serialization-contract.js

@@ -19,7 +19,7 @@ import { must, Unanswerable } from "./query.js";
 import { erasedStores } from "./erased-stores.js";
 import { checkedTypes, CONVERSION_MEMBERS, valueReach } from "./value-reach.js";
 /** The serializer every run reads, whatever the configuration names. */
-const JSON_STRINGIFY = { shape: "global", global: "JSON.stringify" };
+const JSON_STRINGIFY = { global: "JSON.stringify" };
 /** The methods a serializer and a formatter resolve by name on a value that left the analysis. */
 const CONVERSIONS = new Set(["toJSON", "toString"]);
 /** The method a serializer calls on a value that carries one, wherever the value goes. */

package/dist/src/suppress-file.js

@@ -5,9 +5,9 @@
  * ignore file by gaining a maintainer's reason.
  */
 import { CODE } from "./contract/contract.generated.js";
+import { readTargetDocument } from "./fs/document.js";
 import { jsonChunks } from "./json-chunks.js";
-import { joinPath } from "./paths.js";
-import { isRecord, positionAt, walkDocument } from "./json-document.js";
+import { isRecord, positionAt, readStrict, StrictJSONError } from "./json-document.js";
 import { declarationKey } from "./ref.js";
 import { CODE_FORM, SuppressionError, blankReason, isEntryPath, isPartKind, isSymbolRef, siteText, } from "./suppress.js";
 import { message } from "./product.js";
@@ -130,28 +130,27 @@ function byReferenceOf(symbols) {
 }
 /** Reads one document at the target root, binding each record against the run's declarations. */
 function readDocument(host, targetRoot, symbols, shape) {
-    const file = joinPath(targetRoot, shape.file);
-    if (host.kindOf(file) === "absent") {
+    const text = readTargetDocument(host, targetRoot, shape.file);
+    if (text === undefined) {
         return { records: [], refusals: [] };
     }
-    const text = host.readFile(file);
     const malformed = (detail, site = documentSite(shape)) => {
         throw new SuppressionError(shape.mechanism, siteText(site), detail, shape.documentWant);
     };
-    let parsed;
+    let document;
     try {
-        parsed = JSON.parse(text);
+        document = readStrict(text, shape.array);
     }
     catch (error) {
-        return malformed(`${shape.file}: ${message(error)}`);
+        if (!(error instanceof StrictJSONError)) {
+            throw error;
+        }
+        return malformed(error.message, positionAt(text, shape.file, error.offset));
     }
+    const parsed = document.value;
     if (!isRecord(parsed)) {
         return malformed(shape.file);
     }
-    const walk = walkDocument(text, shape.array);
-    if (walk.twice !== undefined) {
-        malformed(`the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`, positionAt(text, shape.file, walk.twice.offset));
-    }
     for (const key of Object.keys(parsed)) {
         if (key !== "description" && key !== shape.array) {
             malformed(`the member ${JSON.stringify(key)} is not one the grammar declares`);
@@ -166,7 +165,7 @@ function readDocument(host, targetRoot, symbols, shape) {
     const records = [];
     const refusals = [];
     held.forEach((value, index) => {
-        const offset = walk.starts[index];
+        const offset = document.starts.get(index);
         const site = offset === undefined ? documentSite(shape) : positionAt(text, shape.file, offset);
         const read = readRecord(value, site, byReference, shape);
         records.push(...read.records);
@@ -278,10 +277,9 @@ function* separatorsEscaped(pieces) {
  * A baseline holding one row per finding, in the order given, which is the report's, and
  * the other language's rows `kept`, Go's rows ahead of TypeScript's and each scheme's in
  * the order given, so two analyzers writing one document in either order write the same
- * bytes, in the form grammar/suppression.md fixes. Every recorded row carries the
- * provenance as its reason. A finding
- * missing a value a row needs, and an identity missing its name or version, are refused
- * rather than written, because the grammar requires a reason on every row.
+ * bytes, in the form grammar/suppression.md fixes. Every row carries the provenance as
+ * its reason, so a finding missing a value a row needs, or an identity missing its name
+ * or version, is refused rather than written.
  */
 export function writeBaseline(findings, provenance, kept = []) {
     if (provenance.analyzer === "" || provenance.version === "") {

package/dist/src/suppress.js

@@ -7,7 +7,7 @@
  * withholds every such finding anyway, and stale otherwise.
  */
 import { KIND_ROWS, SYMBOL_SUBJECTS, } from "./contract/contract.generated.js";
-import { ConfigError } from "./config.js";
+import { UsageError } from "./usage.js";
 import { positionKey } from "./position.js";
 import { isRef } from "./ref.js";
 /**
@@ -15,9 +15,9 @@ import { isRef } from "./ref.js";
  * instruction the analysis cannot carry out. It is a malformed input, so the command line
  * answers it with the usage code.
  */
-export class SuppressionError extends ConfigError {
+export class SuppressionError extends UsageError {
     constructor(mechanism, at, text, want) {
-        super("malformed", at, `${mechanism} ${at}: ${text}: want ${want}`);
+        super(`${mechanism} ${at}: ${text}: want ${want}`);
         this.name = "SuppressionError";
     }
 }

package/dist/src/template-field.js

@@ -12,12 +12,12 @@
  * type, because nothing ties the name to a type.
  */
 import { readComponent } from "./component-files.js";
-import { ConfigError } from "./config.js";
 import { memberNames } from "./member-names.js";
 import { extensionOf, isAbsolutePath, joinPath, normalizePath, relativePath } from "./paths.js";
 import { isComponentFile } from "./position.js";
 import { bytewise } from "./text/compare.js";
 import { filesBelow } from "./fs/tree.js";
+import { UsageError } from "./usage.js";
 /** The kinds of declaration an action can name. */
 const READ_BY_A_TEMPLATE = new Set([
     "method",
@@ -51,18 +51,18 @@ export function readTemplates(host, targetRoot, analysis) {
             }
         }
     };
-    for (const configured of analysis.templateDirs) {
+    for (const configured of analysis.template_dirs) {
         const dir = normalizePath(configured);
         if (isAbsolutePath(dir) ||
             dir === ".." ||
             dir.startsWith("../") ||
             host.kindOf(joinPath(targetRoot, dir)) !== "directory") {
-            throw new ConfigError("malformed", "analysis.template_dirs", `analysis.template_dirs: ${JSON.stringify(configured)} is not a directory below the target root`);
+            throw new UsageError(`analysis.template_dirs: ${JSON.stringify(configured)} is not a directory below the target root`);
         }
         read(dir);
     }
     return {
-        delimiters: analysis.templateDelimiters,
+        delimiters: analysis.template_delimiters,
         files: [...files]
             .map(([path, text]) => ({ path, text }))
             .sort((a, b) => bytewise(a.path, b.path)),

package/dist/src/usage.js

@@ -0,0 +1,10 @@
+/**
+ * A refusal of the invocation: the fix is to the command line or to a document it
+ * names, so the run ends with the usage code before any analysis.
+ */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}

package/dist/src/verbs/analyze.js

@@ -1,6 +1,6 @@
 import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_FAILURE, } from "../contract/contract.generated.js";
 import { runAnalysis, runBaselineWrite, unansweredCounts, } from "../analysis.js";
-import { ConfigError, kindOf } from "../config.js";
+import { kindOf } from "../config.js";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.js";
 import { moduleIdentity } from "../consumers.js";
 import { analyzerProvenance, verdictOf } from "../findings-pass.js";
@@ -14,8 +14,9 @@ import { parseTemplate, TemplateError } from "../reporters/template.js";
 import { resolve } from "../resolve.js";
 import { otherSchemeRows, rowReason, writeBaseline } from "../suppress-file.js";
 import {} from "./verb.js";
+import { UsageError } from "../usage.js";
 import { bytewise } from "../text/compare.js";
-import { diagnose, LANGUAGE, message } from "../product.js";
+import { diagnose, message } from "../product.js";
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS = {
     plain: ["report", "baseline-write", "exit-code", "template"],
@@ -41,10 +42,10 @@ function formatsOf(named, configured) {
     const seen = new Set();
     for (const format of formats) {
         if (!RENDERINGS.has(format)) {
-            throw new ConfigError("malformed", "", `${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
+            throw new UsageError(`${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
         }
         if (seen.has(format)) {
-            throw new ConfigError("malformed", "", `the format ${JSON.stringify(format)} is named twice`);
+            throw new UsageError(`the format ${JSON.stringify(format)} is named twice`);
         }
         seen.add(format);
     }
@@ -130,7 +131,7 @@ function counted(n, noun) {
 function templateOf(host, invoked, named, formats) {
     if (named === undefined || named === "") {
         if (formats.includes("template")) {
-            throw new ConfigError("malformed", "", "the template format renders the template --template names, and none was named");
+            throw new UsageError("the template format renders the template --template names, and none was named");
         }
         return undefined;
     }
@@ -139,7 +140,7 @@ function templateOf(host, invoked, named, formats) {
         source = host.readFile(resolvePath(invoked, named));
     }
     catch (error) {
-        throw new ConfigError("malformed", "", `--template=${named}: ${message(error)}`);
+        throw new UsageError(`--template=${named}: ${message(error)}`);
     }
     try {
         return parseTemplate(source);
@@ -148,7 +149,7 @@ function templateOf(host, invoked, named, formats) {
         if (!(error instanceof TemplateError)) {
             throw error;
         }
-        throw new ConfigError("malformed", "", `--template=${named}: ${error.message}`);
+        throw new UsageError(`--template=${named}: ${error.message}`);
     }
 }
 /**
@@ -162,17 +163,13 @@ function templateOf(host, invoked, named, formats) {
 export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
     const reportPath = option("report");
     if (reportPath === undefined || reportPath === "") {
-        throw new ConfigError("malformed", "", "analyze writes its report to the path --report names, and no path was named");
+        throw new UsageError("analyze writes its report to the path --report names, and no path was named");
     }
     const exitCode = option("exit-code") ?? EXIT_CODE_ON;
     if (exitCode !== EXIT_CODE_ON && exitCode !== EXIT_CODE_OFF) {
-        throw new ConfigError("malformed", "", `--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
+        throw new UsageError(`--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
     }
     const { config, provenance } = resolve(inputs());
-    const kind = config.targetKind;
-    if (kind === "") {
-        throw new ConfigError("missing-target-kind", "target.kind", "target.kind is not set");
-    }
     const invoked = host.workingDirectory();
     const baseline = option("baseline-write");
     const documents = {
@@ -227,7 +224,7 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
             conformance: CONFORMANCE,
             declaredGaps: DECLARED_GAPS,
             target: {
-                kind: kindOf(kind, LANGUAGE),
+                kind: kindOf(config.target.kind),
                 root,
                 identity: moduleIdentity(host, scoped.target),
             },
@@ -249,7 +246,7 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
                 ...unseenLoadNotes(run.unseenLoads),
             ],
         });
-        report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
+        report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.max_findings);
         verdict = verdictOf(result, config);
     }
     catch (error) {

package/dist/src/verbs/explain.js

@@ -1,7 +1,6 @@
 import { EXIT_CLEAN, EXIT_USAGE } from "../contract/contract.generated.js";
 import { runAnalysis } from "../analysis.js";
 import { listing } from "../components.js";
-import { ConfigError } from "../config.js";
 import { OUTSIDE, swept as judged } from "../graph.js";
 import { referenceKey } from "../matrix.js";
 import { partialNotes } from "../partial.js";
@@ -9,6 +8,7 @@ import { resolvePath } from "../paths.js";
 import { positionKey } from "../position.js";
 import { resolve } from "../resolve.js";
 import {} from "./verb.js";
+import { UsageError } from "../usage.js";
 import { bytewise } from "../text/compare.js";
 import { diagnose } from "../product.js";
 /**
@@ -36,10 +36,10 @@ function namedSymbol(option) {
     });
     const [only, ...more] = named;
     if (only === undefined) {
-        throw new ConfigError("malformed", "", "explain explains the symbol --why, --why-live or --why-not names, and none was named");
+        throw new UsageError("explain explains the symbol --why, --why-live or --why-not names, and none was named");
     }
     if (more.length > 0) {
-        throw new ConfigError("malformed", "", `explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`);
+        throw new UsageError(`explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`);
     }
     return only.value;
 }

package/dist/src/verbs/print-projects.js

@@ -2,7 +2,7 @@ import { EXIT_CLEAN } from "../contract/contract.generated.js";
 import { runProjects } from "../analysis.js";
 import { partialNotes } from "../partial.js";
 import { resolvePath } from "../paths.js";
-import { resolveUnkinded } from "../resolve.js";
+import { resolvePartial } from "../resolve.js";
 import {} from "./verb.js";
 import { diagnose } from "../product.js";
 /**
@@ -13,7 +13,7 @@ import { diagnose } from "../product.js";
  * instead, and one that fails the analysis fails this command the same way.
  */
 export const printProjectsVerb = ({ out, err, host, inputs, scope, openClient }) => {
-    const config = resolveUnkinded(inputs());
+    const config = resolvePartial(inputs());
     const scoped = scope();
     const answer = runProjects(openClient(config), host, scoped, config);
     for (const id of answer.configurations) {

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.7",
+  "version": "8.0.0-dev.8",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.7",
+  "version": "8.0.0-dev.8",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",