eslint-plugin-traceability 1.7.1 → 1.8.1

package/lib/src/maintenance/cli.js

@@ -1,27 +1,9 @@
 #!/usr/bin/env node
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runMaintenanceCli = runMaintenanceCli;
-const path_1 = __importDefault(require("path"));
-const detect_1 = require("./detect");
-const batch_1 = require("./batch");
-const update_1 = require("./update");
-const report_1 = require("./report");
-const EXIT_OK = 0;
-const EXIT_STALE = 1;
-const EXIT_USAGE = 2;
-/**
- * Extract the subcommand and its arguments from a raw argv array.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Centralize parsing of CLI command and arguments
- */
-function parseCliInput(rawArgv) {
-    const [, , command, ...rest] = rawArgv;
-    return { command, args: rest };
-}
+const commands_1 = require("./commands");
+const flags_1 = require("./flags");
 /**
  * Maintenance CLI entry point.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -33,217 +15,57 @@ function parseCliInput(rawArgv) {
  * @req REQ-MAINT-SAFE - Provide clear exit codes and avoid unsafe defaults
  */
 function runMaintenanceCli(rawArgv) {
-    const { command, args } = parseCliInput(rawArgv);
+    const initialNormalized = (0, flags_1.normalizeCliArgs)(rawArgv);
+    const { subcommand: command } = initialNormalized;
     if (!command || command === "-h" || command === "--help") {
+        /**
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-SAFE - Handle help requests safely and provide discoverable usage output
+         */
         printHelp();
-        return EXIT_OK;
+        return commands_1.EXIT_OK;
     }
+    // Re-use the normalized arguments object for handlers so that they
+    // receive the subcommand name and its raw argument vector unchanged.
+    const normalized = initialNormalized;
     try {
         switch (command) {
             case "detect":
-                return handleDetect(args);
+                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-DETECT - Dispatch to detection handler
+                return (0, commands_1.handleDetect)(normalized);
             case "verify":
-                return handleVerify(args);
+                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-VERIFY - Dispatch to verification handler
+                return (0, commands_1.handleVerify)(normalized);
             case "report":
-                return handleReport(args);
-            case "update":
-                return handleUpdate(args);
+                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-REPORT - Dispatch to reporting handler
+                return (0, commands_1.handleReport)(normalized);
+            case "update": {
+                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-UPDATE - Dispatch to update handler
+                const result = (0, commands_1.handleUpdate)(normalized);
+                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-SAFE - Print help on usage errors from update
+                if (result === commands_1.EXIT_USAGE) {
+                    printHelp();
+                }
+                return result;
+            }
             default:
+                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-SAFE - Handle unknown commands safely with diagnostics
                 console.error(`Unknown command: ${command}`);
                 printHelp();
-                return EXIT_USAGE;
+                return commands_1.EXIT_USAGE;
         }
     }
     catch (error) {
-        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-        // @req REQ-MAINT-SAFE - Catch unexpected errors and emit concise diagnostics
+        /**
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-SAFE - Catch unexpected errors and surface concise diagnostics without crashing
+         */
         const message = error instanceof Error
             ? error.message
             : "Unknown error in maintenance CLI";
         console.error(`traceability-maint failed: ${message}`);
-        return EXIT_USAGE;
-    }
-}
-/**
- * Initialize default flags for the maintenance CLI.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
- */
-function createDefaultFlags() {
-    return {
-        root: process.cwd(),
-        json: false,
-    };
-}
-/**
- * Handle a single CLI argument and update the flags accordingly.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
- */
-function applyFlag(flags, args, index) {
-    const arg = args[index];
-    if (arg === "--root" && typeof args[index + 1] === "string") {
-        flags.root = path_1.default.resolve(args[index + 1]);
-        return index + 1;
-    }
-    if (arg === "--json") {
-        flags.json = true;
-        return index;
-    }
-    if (arg === "--format" && typeof args[index + 1] === "string") {
-        const value = args[index + 1];
-        if (value === "text" || value === "json") {
-            flags.format = value;
-        }
-        else {
-            throw new Error(`Invalid format: ${value}. Expected 'text' or 'json'.`);
-        }
-        return index + 1;
-    }
-    if (arg === "--from" && typeof args[index + 1] === "string") {
-        flags.from = args[index + 1];
-        return index + 1;
-    }
-    if (arg === "--to" && typeof args[index + 1] === "string") {
-        flags.to = args[index + 1];
-        return index + 1;
-    }
-    if (arg === "--dry-run") {
-        flags.dryRun = true;
-        return index;
-    }
-    return index;
-}
-/**
- * Basic flag parser for maintenance CLI subcommands.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
- */
-function parseFlags(args) {
-    const flags = createDefaultFlags();
-    for (let i = 0; i < args.length; i += 1) {
-        i = applyFlag(flags, args, i);
-    }
-    return flags;
-}
-/**
- * Handle the `detect` subcommand for stale @story annotations.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
- * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
- */
-function handleDetect(args) {
-    const flags = parseFlags(args);
-    const root = flags.root;
-    const stale = (0, detect_1.detectStaleAnnotations)(root);
-    if (flags.json) {
-        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-        // @req REQ-MAINT-REPORT - JSON-friendly output for tooling integration
-        console.log(JSON.stringify({ root, stale }));
-    }
-    else {
-        if (stale.length === 0) {
-            console.log("No stale @story annotations found.");
-        }
-        else {
-            stale.forEach((story) => {
-                console.log(story);
-            });
-            console.log(`Found ${stale.length} stale @story annotation${stale.length === 1 ? "" : "s"}.
-Run 'traceability-maint report' for a structured summary.`);
-        }
-    }
-    return stale.length === 0 ? EXIT_OK : EXIT_STALE;
-}
-/**
- * Handle the `verify` subcommand to validate traceability annotations.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
- * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
- */
-function handleVerify(args) {
-    const flags = parseFlags(args);
-    const root = flags.root;
-    const valid = (0, batch_1.verifyAnnotations)(root);
-    if (valid) {
-        console.log(`All traceability annotations under ${root} are valid.`);
-        return EXIT_OK;
-    }
-    console.log(`Stale or invalid traceability annotations detected under ${root}.\nRun 'traceability-maint detect' or 'traceability-maint report' for details.`);
-    return EXIT_STALE;
-}
-/**
- * Handle the `report` subcommand to generate a maintenance report.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
- * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
- */
-function handleReport(args) {
-    const flags = parseFlags(args);
-    const root = flags.root;
-    const format = flags.format ?? "text";
-    const report = (0, report_1.generateMaintenanceReport)(root);
-    if (format === "json") {
-        console.log(JSON.stringify({ root, report }));
-    }
-    else {
-        if (!report) {
-            console.log("No stale @story annotations found. Nothing to report.");
-        }
-        else {
-            console.log(`# Traceability Maintenance Report for ${root}`);
-            console.log("");
-            console.log("Stale story references:");
-            console.log(report);
-        }
-    }
-    return EXIT_OK;
-}
-/**
- * Handle the `update` subcommand to rewrite @story annotation references.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
- * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
- */
-function handleUpdate(args) {
-    const flags = parseFlags(args);
-    const root = flags.root;
-    if (!flags.from || !flags.to) {
-        console.error("'update' requires --from <oldPath> and --to <newPath>.");
-        printHelp();
-        return EXIT_USAGE;
-    }
-    const from = flags.from;
-    const to = flags.to;
-    if (flags.dryRun) {
-        // For now, we cannot get a per-file diff without changing the maintenance API.
-        // We conservatively reuse generateMaintenanceReport to indicate potential impact.
-        const beforeReport = (0, report_1.generateMaintenanceReport)(root);
-        const potentialChanges = beforeReport ? beforeReport.split("\n").length : 0;
-        const summary = {
-            root,
-            from,
-            to,
-            estimatedStaleCount: potentialChanges,
-        };
-        if (flags.json) {
-            console.log(JSON.stringify({ mode: "dry-run", ...summary }));
-        }
-        else {
-            console.log("Dry run: no files were modified.");
-            console.log(`Would update @story annotations from '${from}' to '${to}' under ${root}.`);
-            console.log(`Estimated stale annotations before update: ${summary.estimatedStaleCount}.`);
-        }
-        return EXIT_OK;
-    }
-    const count = (0, update_1.updateAnnotationReferences)(root, from, to);
-    if (flags.json) {
-        console.log(JSON.stringify({ root, from, to, updated: count }));
-    }
-    else {
-        console.log(`Updated ${count} @story annotation${count === 1 ? "" : "s"} from '${from}' to '${to}' under ${root}.`);
+        return commands_1.EXIT_USAGE;
     }
-    return EXIT_OK;
 }
 /**
  * Print CLI usage help for the maintenance tools.

package/lib/src/maintenance/commands.d.ts

@@ -0,0 +1,32 @@
+import { NormalizedCliArgs } from "./flags";
+export declare const EXIT_OK = 0;
+export declare const EXIT_STALE = 1;
+export declare const EXIT_USAGE = 2;
+/**
+ * Handle the `detect` subcommand for stale @story annotations.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
+ * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ */
+export declare function handleDetect(normalized: NormalizedCliArgs): number;
+/**
+ * Handle the `verify` subcommand to validate traceability annotations.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
+ * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ */
+export declare function handleVerify(normalized: NormalizedCliArgs): number;
+/**
+ * Handle the `report` subcommand to generate a maintenance report.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
+ * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ */
+export declare function handleReport(normalized: NormalizedCliArgs): number;
+/**
+ * Handle the `update` subcommand to rewrite @story annotation references.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
+ * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
+ */
+export declare function handleUpdate(normalized: NormalizedCliArgs): number;

package/lib/src/maintenance/commands.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_USAGE = exports.EXIT_STALE = exports.EXIT_OK = void 0;
+exports.handleDetect = handleDetect;
+exports.handleVerify = handleVerify;
+exports.handleReport = handleReport;
+exports.handleUpdate = handleUpdate;
+/**
+ * Subcommand handlers for the traceability-maint CLI.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - CLI support for detection of stale annotations
+ * @req REQ-MAINT-VERIFY - CLI support for verification of annotations
+ * @req REQ-MAINT-REPORT - CLI support for human-readable reports
+ * @req REQ-MAINT-UPDATE - CLI support for updating annotation references
+ * @req REQ-MAINT-SAFE - Provide clear exit codes and avoid unsafe defaults
+ */
+const detect_1 = require("./detect");
+const batch_1 = require("./batch");
+const update_1 = require("./update");
+const report_1 = require("./report");
+const flags_1 = require("./flags");
+exports.EXIT_OK = 0;
+exports.EXIT_STALE = 1;
+exports.EXIT_USAGE = 2;
+/**
+ * Handle the `detect` subcommand for stale @story annotations.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
+ * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ */
+function handleDetect(normalized) {
+    const flags = (0, flags_1.parseFlags)(normalized);
+    const root = flags.root;
+    const stale = (0, detect_1.detectStaleAnnotations)(root);
+    if (flags.json) {
+        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+        // @req REQ-MAINT-REPORT - JSON-friendly output for tooling integration
+        console.log(JSON.stringify({ root, stale }));
+    }
+    else if (stale.length === 0) {
+        console.log("No stale @story annotations found.");
+    }
+    else {
+        stale.forEach((story) => {
+            console.log(story);
+        });
+        console.log(`Found ${stale.length} stale @story annotation${stale.length === 1 ? "" : "s"}.
+Run 'traceability-maint report' for a structured summary.`);
+    }
+    return stale.length === 0 ? exports.EXIT_OK : exports.EXIT_STALE;
+}
+/**
+ * Handle the `verify` subcommand to validate traceability annotations.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
+ * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ */
+function handleVerify(normalized) {
+    const flags = (0, flags_1.parseFlags)(normalized);
+    const root = flags.root;
+    const valid = (0, batch_1.verifyAnnotations)(root);
+    if (valid) {
+        console.log(`All traceability annotations under ${root} are valid.`);
+        return exports.EXIT_OK;
+    }
+    console.log(`Stale or invalid traceability annotations detected under ${root}.\nRun 'traceability-maint detect' or 'traceability-maint report' for details.`);
+    return exports.EXIT_STALE;
+}
+/**
+ * Handle the `report` subcommand to generate a maintenance report.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
+ * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ */
+function handleReport(normalized) {
+    const flags = (0, flags_1.parseFlags)(normalized);
+    const root = flags.root;
+    const format = flags.format ?? "text";
+    const report = (0, report_1.generateMaintenanceReport)(root);
+    if (format === "json") {
+        console.log(JSON.stringify({ root, report }));
+    }
+    else if (!report) {
+        console.log("No stale @story annotations found. Nothing to report.");
+    }
+    else {
+        console.log(`# Traceability Maintenance Report for ${root}`);
+        console.log("");
+        console.log("Stale story references:");
+        console.log(report);
+    }
+    return exports.EXIT_OK;
+}
+/**
+ * Handle the `update` subcommand to rewrite @story annotation references.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
+ * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
+ */
+function handleUpdate(normalized) {
+    const flags = (0, flags_1.parseFlags)(normalized);
+    const root = flags.root;
+    if (!flags.from || !flags.to) {
+        console.error("'update' requires --from <oldPath> and --to <newPath>.");
+        return exports.EXIT_USAGE;
+    }
+    const from = flags.from;
+    const to = flags.to;
+    if (flags.dryRun) {
+        // For now, we cannot get a per-file diff without changing the maintenance API.
+        // We conservatively reuse generateMaintenanceReport to indicate potential impact.
+        const beforeReport = (0, report_1.generateMaintenanceReport)(root);
+        const potentialChanges = beforeReport ? beforeReport.split("\n").length : 0;
+        const summary = {
+            root,
+            from,
+            to,
+            estimatedStaleCount: potentialChanges,
+        };
+        if (flags.json) {
+            console.log(JSON.stringify({ mode: "dry-run", ...summary }));
+        }
+        else {
+            console.log("Dry run: no files were modified.");
+            console.log(`Would update @story annotations from '${from}' to '${to}' under ${root}.`);
+            console.log(`Estimated stale annotations before update: ${summary.estimatedStaleCount}.`);
+        }
+        return exports.EXIT_OK;
+    }
+    const count = (0, update_1.updateAnnotationReferences)(root, from, to);
+    if (flags.json) {
+        console.log(JSON.stringify({ root, from, to, updated: count }));
+    }
+    else {
+        console.log(`Updated ${count} @story annotation${count === 1 ? "" : "s"} from '${from}' to '${to}' under ${root}.`);
+    }
+    return exports.EXIT_OK;
+}

package/lib/src/maintenance/detect.d.ts

@@ -2,5 +2,7 @@
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @param codebasePath Path to the codebase root, treated as a workspace root and resolved against process.cwd().
+ * @returns A de-duplicated array of stale @story paths (as strings) whose resolved targets no longer exist on disk.
  */
 export declare function detectStaleAnnotations(codebasePath: string): string[];

package/lib/src/maintenance/detect.js

@@ -42,6 +42,8 @@ const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @param codebasePath Path to the codebase root, treated as a workspace root and resolved against process.cwd().
+ * @returns A de-duplicated array of stale @story paths (as strings) whose resolved targets no longer exist on disk.
  */
 function detectStaleAnnotations(codebasePath) {
     const cwd = process.cwd();
@@ -58,6 +60,8 @@ function detectStaleAnnotations(codebasePath) {
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Iterate over all files in the isolated workspace root
     const files = (0, utils_1.getAllFiles)(workspaceRoot);
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Loop over each workspace file to inspect its @story annotations
     for (const file of files) {
         processFileForStaleAnnotations(file, workspaceRoot, cwd, stale);
     }

package/lib/src/maintenance/flags.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Parsed representation of raw CLI input (argv) for the maintenance tools.
+ *
+ * Separates Node/V8 internals from the actual subcommand and its arguments.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+export interface ParsedCliInput {
+    /**
+     * The raw argv as passed to the Node.js process (e.g., process.argv).
+     */
+    readonly argv: string[];
+    /**
+     * The Node.js executable path (argv[0]).
+     */
+    readonly node: string;
+    /**
+     * The executed script path (argv[1]).
+     */
+    readonly script: string;
+    /**
+     * The maintenance subcommand being invoked (first argument after script).
+     */
+    readonly subcommand: string | undefined;
+    /**
+     * Remaining arguments after the subcommand, to be interpreted as flags
+     * or positional arguments for that subcommand.
+     */
+    readonly args: string[];
+}
+/**
+ * Parse raw Node.js argv into a structured CLI input for the maintenance tools.
+ *
+ * This performs only minimal, predictable splitting to support higher-level
+ * flag parsing in a safe and testable way.
+ *
+ * @param argv - Raw argv array, usually process.argv.
+ * @returns ParsedCliInput with node, script, subcommand, and remaining args.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+export declare function parseCliInput(argv: string[]): ParsedCliInput;
+/**
+ * Normalized view of CLI arguments relevant to a maintenance subcommand.
+ *
+ * This strips away Node/V8 internals and script paths, exposing only the
+ * subcommand name and its raw arguments for further flag parsing.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+export interface NormalizedCliArgs {
+    /**
+     * The maintenance subcommand being invoked (first argument after script).
+     */
+    readonly subcommand: string | undefined;
+    /**
+     * Remaining arguments after the subcommand, to be interpreted as flags
+     * or positional arguments for that subcommand.
+     */
+    readonly args: string[];
+}
+/**
+ * Normalize raw argv into a subcommand-centric view for flag parsing.
+ *
+ * Uses parseCliInput to safely separate Node/V8 internals from the
+ * subcommand and its arguments, then exposes only the pieces relevant
+ * to subcommand-specific flag parsing.
+ *
+ * @param rawArgv - Raw argv array, usually process.argv.
+ * @returns NormalizedCliArgs with subcommand and remaining args.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+export declare function normalizeCliArgs(rawArgv: string[]): NormalizedCliArgs;
+export interface ParsedFlags {
+    root: string;
+    json: boolean;
+    format?: "text" | "json";
+    from?: string;
+    to?: string;
+    dryRun?: boolean;
+}
+/**
+ * Basic flag parser for maintenance CLI subcommands.
+ *
+ * Consumes already-normalized CLI arguments (subcommand and its raw args)
+ * and produces a ParsedFlags structure with minimal, predictable behavior.
+ *
+ * @param normalized - Normalized CLI arguments for a maintenance subcommand.
+ * @returns ParsedFlags with defaults applied and any recognized flags set.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+export declare function parseFlags(normalized: NormalizedCliArgs): ParsedFlags;