@sybelblue/prairielearn-navigator 1.1.0 → 1.1.2

package/dist/core/config.d.ts

@@ -1,9 +1,22 @@
+import * as z from "zod";
 import { Diagnostic } from "./diagnostic";
 import { PlVersion } from "./plVersion";
 import { RuleId } from "./rules/registry";
 /** Looked up in the course root, next to infoCourse.json. */
 export declare const configFileName = ".pl-navigator.jsonc";
-type RuleSetting = "off" | "warning" | "error";
+export declare const ruleSetting: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+    info: "info";
+    off: "off";
+}>;
+type RuleSetting = z.infer<typeof ruleSetting>;
+export declare const severitySetting: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+    info: "info";
+    ignored: "ignored";
+}>;
 /** A glob and the directory it is relative to. */
 interface Exclude {
     base: string;
@@ -20,7 +33,7 @@ export interface NavigatorConfig {
 /** Whether `file` matches one of the config's `excludes`. */
 export declare function isExcluded(config: NavigatorConfig, file: string): boolean;
 /** Same keys as the config file; from CLI flags or VS Code settings. */
-export type ConfigOverrides = Partial<Record<keyof NavigatorConfig, unknown>>;
+export type ConfigOverrides = Partial<Record<keyof typeof fields, unknown>>;
 /** A config problem, located in `file` when it came from one. */
 export type ConfigProblem = Diagnostic & {
     file?: string;
@@ -43,4 +56,25 @@ export declare function loadConfig(courseRoot: string | null, options?: {
     overridesBaseDir?: string;
     defaults?: Partial<NavigatorConfig>;
 }): LoadedConfig;
+type Report = (message: string, path: (string | number)[], severity?: Diagnostic["severity"]) => void;
+/** One config source being applied. */
+interface FieldContext {
+    config: NavigatorConfig;
+    /** What relative paths in this source are relative to. */
+    baseDir: string;
+    report: Report;
+}
+type Field = (key: string, value: unknown, ctx: FieldContext) => void;
+declare const fields: {
+    unusedQuestions: Field;
+    unusedTags: Field;
+    unusedAssessmentSets: Field;
+    missingQuestionInfo: Field;
+    plVersion: Field;
+    schemaCacheDir: Field;
+    excludes: Field;
+    rules: Field;
+};
+/** Every key a config source may set, besides `$schema`. */
+export declare const configKeys: readonly string[];
 export {};

package/dist/core/diagnostic.d.ts

@@ -3,11 +3,22 @@
  * Ranges are character offsets into the checked text; adapters convert them
  * to their own position types.
  */
-type Severity = "error" | "warning";
+type Severity = "error" | "warning" | "info";
 interface RelatedInfo {
     path: string;
     message: string;
 }
+export type DiagnosticMetadata = {
+    kind: "schema-required-property";
+    /** JSON path of the object that requires the property. */
+    path: (string | number)[];
+    property: string;
+} | {
+    kind: "schema-pattern";
+    /** JSON path of the value that failed the pattern. */
+    path: (string | number)[];
+    pattern: string;
+};
 export interface Diagnostic {
     startOffset: number;
     endOffset: number;
@@ -15,6 +26,7 @@ export interface Diagnostic {
     severity: Severity;
     code?: string;
     related?: RelatedInfo[];
+    metadata?: DiagnosticMetadata;
 }
 /** 1-based line/column for a character offset. */
 export declare function offsetToPosition(text: string, offset: number): {

package/dist/core/questionDirs.d.ts

@@ -0,0 +1,13 @@
+/** A directory under questions/ that PrairieLearn will fail to load. */
+export interface QuestionDirWithoutInfo {
+    /** Absolute. */
+    dir: string;
+    /** The file the diagnostic is shown on: question.html, else the first file. */
+    anchor: string;
+}
+/**
+ * Directories under `<courseRoot>/questions` with files but no info.json and
+ * no question anywhere below them. PrairieLearn walks questions/ the same way
+ * (skipping hidden entries) and records each as "Missing JSON file".
+ */
+export declare function questionDirsWithoutInfo(courseRoot: string): QuestionDirWithoutInfo[];

package/dist/core/referenceIndex.d.ts

@@ -15,14 +15,23 @@ export interface Use {
         column: number;
     };
 }
+/** Names defined course-wide in infoCourse.json that a file uses. */
+export interface UsedNames {
+    /** A question's `tags`. */
+    tags: string[];
+    /** An assessment's `set`. */
+    assessmentSets: string[];
+}
 /**
  * Reverse index of every file reference in one course: which files
- * reference a given target. Updated one file at a time.
+ * reference a given target. Also records the tags and assessment sets each
+ * file uses. Updated one file at a time.
  */
 export declare class ReferenceIndex {
     readonly courseRoot: string;
     private plDate;
     private usesByFile;
+    private namesByFile;
     private filesByTarget;
     /** How many targets lie under each directory, to answer directory events quickly. */
     private targetsUnder;
@@ -34,6 +43,10 @@ export declare class ReferenceIndex {
     remove(file: string): void;
     /** Every file holding references. */
     files(): string[];
+    /** Tags and assessment sets `file` uses, if it is a question or assessment. */
+    namesIn(file: string): UsedNames | undefined;
+    /** Every name of this kind used anywhere in the course. */
+    namesUsed(kind: keyof UsedNames): Set<string>;
     /** References made by `file`. */
     usesIn(file: string): Use[];
     /**

package/dist/core/rules/impls.d.ts

@@ -12,3 +12,7 @@ export declare function schemaRule(name: SchemaName): RuleImpl;
 export declare function referencesExist(rule: string): RuleImpl;
 /** Warns on every occurrence of a question used more than once in a file. */
 export declare const duplicateQuestionIds: RuleImpl;
+/** Notes a question that no assessment uses, on its title. */
+export declare const unusedQuestion: RuleImpl;
+export declare const unusedTags: RuleImpl;
+export declare const unusedAssessmentSets: RuleImpl;

package/dist/core/rules/registry.d.ts

@@ -14,6 +14,10 @@ declare const otherRules: {
     readonly "json-syntax": (readonly ["*", "infoCourse.json" | "courseInstances/**/infoCourseInstance.json" | "courseInstances/**/assessments/**/infoAssessment.json" | "questions/**/info.json" | "elements/*/info.json" | "elementExtensions/*/*/info.json", import("./types").RuleImpl])[];
     readonly schema: readonly [readonly ["*", "infoCourse.json", import("./types").RuleImpl], readonly ["*", "courseInstances/**/infoCourseInstance.json", import("./types").RuleImpl], readonly ["*", "courseInstances/**/assessments/**/infoAssessment.json", import("./types").RuleImpl], readonly ["*", "questions/**/info.json", import("./types").RuleImpl], readonly ["*", "elements/*/info.json", import("./types").RuleImpl], readonly ["*", "elementExtensions/*/*/info.json", import("./types").RuleImpl]];
     readonly "duplicate-question-id": readonly [readonly ["*", "courseInstances/**/assessments/**/infoAssessment.json", import("./types").RuleImpl]];
+    readonly "unused-question": readonly [readonly ["*", "questions/**/info.json", import("./types").RuleImpl]];
+    readonly "unused-tag": readonly [readonly ["*", "infoCourse.json", import("./types").RuleImpl]];
+    readonly "unused-assessment-set": readonly [readonly ["*", "infoCourse.json", import("./types").RuleImpl]];
+    readonly "question-info-missing": readonly [];
 };
 /**
  * Every validation rule, by id. Ids appear in diagnostic codes as
@@ -21,6 +25,8 @@ declare const otherRules: {
  */
 export declare const rules: Record<RuleId, readonly RuleEntry[]>;
 export type RuleId = keyof typeof otherRules | RefRuleId;
+/** Rules that read the reference index; without one they report nothing. */
+export declare const indexedRules: readonly RuleId[];
 export declare function isRuleId(id: string): id is RuleId;
 export declare function ruleDiagnosticCode(id: RuleId): string;
 export {};

package/dist/core/rules/run.d.ts

@@ -1,6 +1,7 @@
 import { NavigatorConfig } from "../config";
 import { Diagnostic } from "../diagnostic";
 import { IsoDate } from "../plVersion";
+import { ReferenceIndex } from "../referenceIndex";
 import { SchemaStore } from "../schemas";
 import { RuleId } from "./registry";
 import { RuleImpl, RuleTable } from "./types";
@@ -15,4 +16,10 @@ export declare function runRules(filePath: string, text: string, options: {
     courseRoot: string;
     config: NavigatorConfig;
     schemas: SchemaStore;
+    references?: ReferenceIndex;
 }): Promise<Diagnostic[]>;
+/**
+ * Runs the rules that look at a course as a whole rather than one file.
+ * Returns diagnostics by the absolute path of the file each is shown on.
+ */
+export declare function runCourseRules(courseRoot: string, config: NavigatorConfig): Map<string, Diagnostic[]>;

package/dist/core/rules/types.d.ts

@@ -1,6 +1,7 @@
 import { Diagnostic } from "../diagnostic";
 import { JsonDoc } from "../json";
 import { IsoDate, PlVersion, VersionRange } from "../plVersion";
+import { ReferenceIndex } from "../referenceIndex";
 import { SchemaStore } from "../schemas";
 /** Everything a rule may inspect about the file being checked. */
 export interface RuleContext {
@@ -14,6 +15,11 @@ export interface RuleContext {
     /** The date `plVersion` stands for, used to select version-ranged rules. */
     plDate: IsoDate;
     schemas: SchemaStore;
+    /**
+     * The course's reference index, when the caller has built one; cross-file
+     * rules report nothing without it.
+     */
+    references?: ReferenceIndex;
 }
 export type RuleImpl = (ctx: RuleContext) => Diagnostic[] | Promise<Diagnostic[]>;
 /**